{"id":20916994,"url":"https://github.com/tidalcycles/vim-tidal","last_synced_at":"2025-04-06T09:10:16.252Z","repository":{"id":18577920,"uuid":"21780950","full_name":"tidalcycles/vim-tidal","owner":"tidalcycles","description":"Vim plugin for TidalCycles","archived":false,"fork":false,"pushed_at":"2024-06-22T21:16:09.000Z","size":110,"stargazers_count":224,"open_issues_count":29,"forks_count":56,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-29T14:53:21.755Z","etag":null,"topics":["tidalcycles","tmux","vim","vim-plugins"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tidalcycles.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-13T02:06:06.000Z","updated_at":"2024-09-21T12:18:59.000Z","dependencies_parsed_at":"2024-04-15T06:15:43.212Z","dependency_job_id":"2f803c9e-92fd-46e7-b68a-aff82720f46e","html_url":"https://github.com/tidalcycles/vim-tidal","commit_stats":{"total_commits":135,"total_committers":17,"mean_commits":"7.9411764705882355","dds":"0.31851851851851853","last_synced_commit":"e440fe5bdfe07f805e21e6872099685d38e8b761"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidalcycles%2Fvim-tidal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidalcycles%2Fvim-tidal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidalcycles%2Fvim-tidal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidalcycles%2Fvim-tidal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tidalcycles","download_url":"https://codeload.github.com/tidalcycles/vim-tidal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457803,"owners_count":20941906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["tidalcycles","tmux","vim","vim-plugins"],"created_at":"2024-11-18T16:29:19.975Z","updated_at":"2025-04-06T09:10:16.235Z","avatar_url":"https://github.com/tidalcycles.png","language":"Vim Script","funding_links":[],"categories":["Vim Script"],"sub_categories":[],"readme":"# vim-tidal #\n\nA Vim/NeoVim plugin for [TidalCycles](http://tidalcycles.org), the language for\nlive coding musical patterns written in Haskell.\n\nThis plugin by default uses [tmux](https://tmux.github.io/), a known and loved\nterminal multiplexer, for communicating with between Vim and the Tidal\ninterpreter.  It was originally based on\n[vim-slime](https://github.com/jpalardy/vim-slime).\n\n![](http://i.imgur.com/frOLFFI.gif)\n\nIf you are using Vim8 or NeoVim, you can use the native Terminal feature instead\nof tmux. Read the Configuration section on how to enable it.\n\n[![asciicast](https://asciinema.org/a/224891.svg)](https://asciinema.org/a/224891)\n\n## Getting Started ##\n\n1. Start livecoding with Vim by simply running:\n\n   ```bash\n   $ tidalvim\n   ```\n\n   This creates a tmux session with Vim and Tidal running on different panes.\n\n2. Write something like this:\n\n   ```haskell\n   d1 $ sound \"bd sn\"\n   ```\n\n3. While being on that line, press `\u003cc-e\u003e` (Control + E) to evaluate it.\n\n   You should see Vim flash that line for a second and a chunk of text appear on\n   your Tidal interpreter.  If you already have SuperDirt or other synth running,\n   you should hear a kick and a snare :)\n\n## Install ##\n\nMake sure you have TidalCycles installed, with SuperDirt running. See [the Tidal wiki](https://tidalcycles.org/index.php/Userbase) for more information.\n\n### Install tmux ###\n\n#### Ubuntu/Debian ####\n\nYou can install it from the main repos:\n\n    $ sudo apt-get install tmux\n\n#### OSX ####\n\n    $ brew install tmux\n\n#### Windows ####\n\nThere seems to be [a Cygwin package for\ntmux](https://cygwin.com/cgi-bin2/package-cat.cgi?file=x86%2Ftmux%2Ftmux-1.9a-1\u0026grep=tmux),\nbut at present it is [not working](https://github.com/microsoft/terminal/issues/5132#issuecomment-604560893) with any known terminal emulator for Windows. As such, this plugin has only been tested with the *Windows native* build of [Neovim](https://github.com/tidalcycles/vim-tidal#neovim-terminal-target).\n\n\n### Install plugin ###\n\nI recommend using a Vim plugin manager like\n[Plug](https://github.com/junegunn/vim-plug).  Check the link for instructions\non installing and configuring.  If you don't want a plugin manager, you can\nalso download the latest release\n[here](https://github.com/tidalcycles/vim-tidal/releases) and extract the\ncontents on your Vim directory (usually `~/.vim/`).\n\nFor example, with Plug you need to:\n\n  * Edit your `.vimrc` file and add these lines:\n\n```vim\nPlug 'tidalcycles/vim-tidal'\n```\n\n  * Restart Vim and execute `:PlugInstall` to automatically download and\n    install the plugins.\n\n#### UNIX-based Systems ####\n\nIf you are on a UNIX-based operating system (Linux distributions, MacOS, etc.), go to the plugin repository and run `make install`:\n\n(if you are using NeoVim and you won't run tmux then you don't need to run `make install` to be able to load the plugin inside NeoVim)\n\n    $ cd ~/.vim/plugged/vim-tidal\n    $ sudo make install\n\nThis creates symlinks on `/usr/local/bin` for `tidal` and `tidalvim` scripts.\nYou can remove them later if you want with `make uninstall`.\n\n#### Windows ####\n\n:warning: **This plugin has only been tested on Windows 10 using Neovim \u003e0.5**\n\nIf you are on Windows, add the `vim-tidal\\bin` directory to your `PATH` user environment variable:\n\n    1. Click the `Start` button\n    2. Type \"Edit the system environment variables\" and hit `enter` or click on the search result\n    3. Click the button labeled `Environment variables...`\n    4. In the `User variables for [username]` table, click the entry for the `Path` variable, followed by the `Edit...` button beneath the same table\n    5. Click the `New` button in the following dialog, enter the *full path* to the `vim-tidal\\bin` directory, and click `OK` until all the preceding dialogs are closed.\n\nNote: The full path to the `vim-tidal\\bin` directory, will look something like `C:\\Users\\[username]\\AppData\\Local\\nvim\\plugged\\vim-tidal\\bin`, assuming you are using vim-plug as this document recommends.\n\n#### Final Installation Note ####\n\nMake sure to have the `filetype plugin on` setting on your .vimrc, otherwise\nplugin won't be loaded when opening a .tidal file.\n\n### Older Tidal versions (pre 1.0) ###\n\nTidal 1.0 introduces some breaking changes, so if haven't upgraded yet, you can\nstill use this plugin with an older version. Just point your Plug entry to use\nthe `tidal-0.9` branch.\n\nFirst change your Plug line on your `.vimrc` to:\n\n```vim\nPlug 'tidalcycles/vim-tidal', {'branch': 'tidal-0.9'}\n```\n\nThen on Vim run `:PlugInstall` to update your plugin.\n\n\n## Usage\n\nThis plugin comes bundled with two Bash scripts: `tidalvim` and `tidal`.\n\n### `tidalvim`\n\n`tidalvim` starts a tmux session with the screen horizontally splitted, having\nVim on the upper pane and the Tidal interpreter on the lower pane.  This is the\nsimplest way to start using Tidal with Vim.\n\nYou don't have to use `tidalvim` necessarily. If you have a more complex setup\nor just want to use Vim outside of tmux, you can use `tidal`.  See below.\n\n### `tidal`\n\n`tidal` fires up GHCi (the Glasgow Haskell interpreter) and runs a bootstrap\nfile that loads Tidal up. `tidalvim` uses this script to start the Tidal\ninterpreter on the lower pane.  You can even use it standalone (without Vim) by\nsimply running `tidal` from your shell.\n\n```haskell\n$ tidal\nGHCi, version 7.10.3: http://www.haskell.org/ghc/  :? for help\ntidal\u003e d1 $ sound \"bd sn\"\ntidal\u003e :t density 2 $ n \"0 1\"\ndensity 2 $ n \"0 1\" :: Pattern ParamMap\n```\n\nSo, in case you don't want to use `tidalvim`, just run the following on another\nterminal:\n\n```bash\ntmux new-session -s tidal tidal\n```\n\nWhat `tidal` does is actually run `ghci` with the argument `-ghci-script\nTidal.ghci`.  [Tidal.ghci](Tidal.ghci) is found at the root of the repository,\nand is responsible for bootstraping Tidal.  See Configure section for more on\nhow to customize Tidal bootstraping process.  Any extra arguments when running\n`tidal` will be delegated to `ghci`.\n\n### Commands\n\nThese are some of the commands that can be run from Vim command line:\n\n* `:\u003crange\u003eTidalSend`: Send a `[range]` of lines. If no range is provided the\n  current line is sent.\n\n* `:TidalSend1 {text}`: Send a single line of text specified on the command\n  line.\n\n* `:TidalConfig`: Configure tmux socket name and target pane\n\n* `:TidalSilence [num]`: Silence stream number `[num]` by sending `d[num]\n  silence`.\n\n* `:TidalPlay [num]`: Send first ocurrence of stream number `[num`] from the\n  current cursor position.\n\n* `:TidalHush`: Silences all streams by sending `hush`.\n\n* `:TidalGenerateCompletions {path}`: Generate dictionary for Dirt-Samples\n  completion (path is optional).\n\n### Default bindings\n\nUsing one of these key bindings you can send lines to Tidal:\n\n* `\u003cc-e\u003e` (Control+E), `\u003clocalleader\u003ess`: Send current inner paragraph.\n* `\u003clocalleader\u003es`: Send current line or current visually selected block.\n\n`\u003cc-e\u003e` can be called on either Normal, Visual, Select or Insert mode, so it is\nprobably easier to type than `\u003clocalleader\u003ess` or `\u003clocalleader\u003es`.\n\nThere are other bindings to control Tidal like:\n\n* `\u003clocalleader\u003es[num]`: Call `:TidalPlay [num]`\n* `\u003clocalleader\u003e[num]`: Call `:TidalSilence [num]`\n* `\u003clocalleader\u003eh`, `\u003cc-h\u003e`: Call `:TidalHush`\n\n#### About `\u003clocalleader\u003e`\n\nThe `\u003cleader\u003e` key is a special key used to perform commands with a sequence of\nkeys.  The `\u003clocalleader\u003e` key behaves as the `\u003cleader\u003e` key, but is *local* to\na buffer.  In particular, the above bindings only work in buffers with the\n\"tidal\" file type set, e.g. files whose file type is `.tidal`\n\nBy default, there is no `\u003clocalleader\u003e` set.  To define one, e.g. for use with\na comma (`,`), write this on your `.vimrc` file:\n\n```vim\nlet maplocalleader=\",\"\n```\n\nReload your configuration (or restart Vim), and after typing `,ss` on a few\nlines of code, you should see those being copied onto the Tidal interpreter on\nthe lower pane.\n\n\n## Configure ##\n\n### GHCI\n\nBy default, `vim-tidal` uses the globally installed GHCI to launch the REPL.\nIf you have installed Tidal through Stack (`stack install tidal`) or some other\nmeans, you can specify another command to use with `g:tidal_ghci`.\n\nFor example, if one installed Tidal with Stack, they would use:\n\n```vim\nlet g:tidal_ghci = \"stack exec ghci --\"\n```\n\n### Tidal Boot File\n\nA \"Tidal boot file\" is a file that may be used to initialise Tidal within GHCI.\nA custom boot file can be specified using the `g:tidal_boot` variable.\n\nIn the case that `g:tidal_boot` is unspecified, vim-tidal will traverse parent\ndirectories until one of either `BootTidal.hs`, `Tidal.ghci` or `boot.tidal` are\nfound.\n\nIf no tidal boot file can be found by traversing parent directories, tidal will\ncheck the `g:tidal_boot_fallback` variable for a fallback boot file. This\nvariable is useful for specifying a default user-wide tidal boot file on your\nsystem, while still allowing each tidal project to optionally use their own\ndedicated, local tidal boot file. By default, `g:tidal_boot_fallback` will point\nto the `Tidal.ghci` file provided with this plugin.\n\n### Default bindings ###\n\nBy default, there are two normal keybindings and one for visual blocks using\nyour `\u003clocalleader\u003e` key.  If you don't have one defined, set it on your\n`.vimrc` script with `let maplocalleader=\",\"`, for example.\n\nIf you don't like some of the bindings or want to change them, add this line to\ndisable them:\n\n```vim\nlet g:tidal_no_mappings = 1\n```\n\nSee section Mappings on [ftplugin/tidal.vim](ftplugin/tidal.vim) and copy the\nbindings you like to your `.vimrc` file and modify them.\n\n### Vim Terminal\n\nOn both Vim (version 8 or above) and NeoVim, the default target in which we boot\nTidal with GHCi is the native terminal.\n\nWhile it is the default, it can also be specified manually with the following:\n\n```vim\nlet g:tidal_target = \"terminal\"\n```\n\nOpen a file with a `.tidal` suffix, write and send a line of code to tidal, and\nthe tidal terminal will open in a window below your editor.\n\nUse standard vim window navigation controls to focus the terminal (ie `\u003cC-w\u003e down/up`)\n\nYou can learn more about the native Vim terminal here:\n\nhttps://vimhelp.org/terminal.txt.html\n\n### tmux (alternative to Vim terminal)\n\nBefore Vim had native terminal support, this plugin provided a \"tmux\" target in\norder to allow for multiplexing the user's terminal via the 3rd party CLI tool.\nIf you have `tmux` installed and you wish to use it instead of the native Vim\nterminal, you can enable this target with the following:\n\n```vim\nlet g:tidal_target = \"tmux\"\n```\n\nThis target will be enabled automatically in the case that the version of Vim in\nuse does not have native terminal support.\n\nYou can configure tmux socket name and target pane by typing `\u003clocalleader\u003ec`\nor `:TidalConfig`.  This will prompt you first for the socket name, then for\nthe target pane.\n\nAbout the target pane:\n\n* `\":\"` means current window, current pane (a reasonable default)\n* `\":i\"` means the ith window, current pane\n* `\":i.j\"` means the ith window, jth pane\n* `\"h:i.j\"` means the tmux session where h is the session identifier (either\n  session name or number), the ith window and the jth pane\n\nWhen you exit Vim you will lose that configuration. To make this permanent, set\n`g:tidal_default_config` on your `.vimrc`.  For example, suppose you want to run\nTidal on a tmux session named `omg`, and the GHCi interpreter will be running\non the window 1 and pane 0.  In that case you would need to add this line:\n\n```vim\nlet g:tidal_default_config = {\"socket_name\": \"default\", \"target_pane\": \"omg:1.0\"}\n```\n\n### Optional Supercollider Terminal\n\nVim-tidal provides an option for automatically running the supercollider\ncommand-line tool `sclang` alongside the Tidal GCHI terminal. By default this\nterminal is disabled, however it can be enabled with the following:\n\n```vim\nlet g:tidal_sc_enable = 1\n```\n\nThis can be useful to avoid the need to manually run sclang in a separate\nterminal or to open the supercollider IDE.\n\nA custom supercollider boot file can be specified by assigning its path to the\n`g:tidal_sc_boot` variable.\n\nIn the case that `g:tidal_sc_boot` is unspecified, vim-tidal will traverse\nparent directories until one of either `boot.sc` or `boot.scd` are found.\n\nIf no supercollider boot file can be found by traversing parent directories,\ntidal will check the `g:tidal_sc_boot_fallback` variable for a fallback boot\nfile. This variable is useful for specifying a default user-wide supercollider\nboot file on your system, while still allowing each tidal project to optionally\nuse their own dedicated, local supercollider boot file.\n\nBy default, `g:tidal_sc_boot_fallback` will point to the `boot.sc` file provided\nwith this plugin which simply starts SuperDirt with the default settings.\n\n### Miscellaneous ###\n\nWhen sending a paragraph or a single line, vim-tidal will \"flash\" the selection\nfor some milliseconds.  By default duration is set to 150ms, but you can modify\nit by setting the `g:tidal_flash_duration` variable.\n\nWrite the paste buffer to an external text file:\n\n```vim\nlet g:tidal_paste_file = \"/tmp/tidal_paste_file.txt\"\n```\n\nFor customizing the startup script for defining helper functions, see below.\n\n\n## `tidalvim` and `tidal` ##\n\n`tidalvim`  is just an example script.  You can copy and customize it as much\nas you want.  See `man tmux` if you want to know more about its options.\n\nFor example, if you want to split horizontally instead of vertically, change\nthe `-v` for `-h` option in the `split-window` line:\n\n```diff\n- split-window -v -t $SESSION   \\; \\\n+ split-window -h -t $SESSION   \\; \\\n```\n\nBoth scripts have some options that you can specify as environment variables.\nFor example:\n\n```\nTIDAL_TEMPO_IP=192.168.0.15 SESSION=whatever tidalvim\n```\n\nThis would start Tidal synced to another Tidal on 192.168.0.15, and it would\ntry to attach or create a tmux sesssion called `whatever`.\n\nThe following is a list of all variables that can be changed:\n\n* `FILE`: File name to open with Vim (default: `$(date +%F).tidal`, e.g.\n  `2017-03-09.tidal`).  The `.tidal` extension is important (you can run\n  `:setfiletype haskell.tidal` in case you won't use a .tidal file here).\n\n* `SESSION`: tmux session name (default: `tidal`)\n\n* `TIDAL_BOOT_PATH`: Tidal Bootstrap file, a .ghci file (default: `Tidal.ghci`)\n\n* `TIDAL_TEMPO_IP`: Tells Tidal to sync tempo with another Tidal instance on\n  the specified IP (default: `127.0.0.1`, i.e. use local)\n\n* `VIM`: Vim command (default: `vim`)\n\n* `GHCI`: GHCi command (default: `ghci`)\n\n* `TMUX`: tmux command (default: `tmux`)\n\n### Customizing Tidal startup ###\n\nIn case you have defined some helper functions, and/or you want to import other\nmodules into Tidal, you can edit the `Tidal.ghci` found at the root of the\nrepository.\n\nHowever doing this could eventually cause conflicts when trying to upgrade\nvim-tidal, so instead I recommend that you define a different `.ghci` file that\nfirst loads `Tidal.ghci` and includes all your custom definitions.\n\nHere is an example.  Suppose you define a `myStuff.ghci` file on your home\ndirectory like this:\n\n```haskell\n--file: ~/myStuff.ghci\n\n-- Bootstrap Tidal\n-- Replace this path if you have vim-tidal installed elsewhere\n:script ~/.vim/bundle/vim-tidal/Tidal.ghci\n\n:{\nlet foo = every 4 $ within (0.75, 1) (density 4)\n    bar = n \"\u003c0 1 2 4\u003e\"\n:}\n```\n\nThen, you would run `tidal` or `tidalvim` with `TIDAL_BOOT_PATH` pointing to\nyour new script file:\n\n```bash\nTIDAL_BOOT_PATH=~/myStuff.ghci tidalvim\n```\n\nPlease note that this a `.ghci` script, not a Haskell module. So multiline\ndefinitions need to be wrapped around `:{` and `:}`, as shown in the example\nabove.\n\n\n## Troubleshooting\n\nHere is a list of common problems.\n\n\u003e I press `\u003cc-e\u003e` but it moves the screen down by one line, and nothing else happens\n\nUsually `\u003cc-e\u003e` is used to move the screen forward by one line, but vim-tidal remaps\nthis to sending current paragraph. If this is happening you either:\n\n1. Opened a file without `.tidal` extension, or changed file type accidentally.\n   *Solution*: Reopen Vim or set filetype for current buffer with `:set\n   ft=tidal`.\n2. Have `g:tidal_no_mappings` setting on your `.vimrc`. This disables all\n   mappings.\n   *Solution*: Remove `\u003cc-e\u003e` binding, or rebind to something else.\n\nIt could also be that you do not have `filetype plugin on` setting in your\n.vimrc.  Make sure you have that setting defined.\n\n\u003e I press `\u003cc-e\u003e` and nothing else happens\n\nThis means that vim-tidal is sending text to tmux, but to the wrong\nsession/window/pane.\n*Solution*: Check that you have configure the socket name and target pane\ncorrectly.  See the Configure section above for more information.\n\nIf you have any question or something does not work as expected, there are many\nchannels you can go to:\n\n* [Chat](https://talk.lurk.org/): Reach out at the `#tidal` and `#vim` channels\n* [GitHub issues](https://github.com/tidalcycles/vim-tidal/issues/new)\n* [Official Tidal forum](https://we.lurk.org/postorius/lists/tidal.we.lurk.org/)\n\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\n\u003chttps://github.com/tidalcycles/vim-tidal\u003e.  This project is intended to be a\nsafe, welcoming space for collaboration, and contributors are expected to\nadhere to the [Contributor Covenant](http://contributor-covenant.org) code of\nconduct.\n\n\n## License\n\nRefer to the [LICENSE](LICENSE) file\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidalcycles%2Fvim-tidal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftidalcycles%2Fvim-tidal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidalcycles%2Fvim-tidal/lists"}