home - plugins - tutorials - showcase - history - manual - design

dublang user manual

this reference manual describes the dublang features, ideas and concepts


shebang are lines starting by the two characters #! followed by the dublang plugin name

shebang defines regions in dublang language and can be added at any place, multiple times

for instance, the line #!supercollider defines a region to write SuperCollider code


{ SinOsc.ar([220, 140]) }.play


d1 $ sound "808bd(3,8)"
   # shape 0.2


services handles live coding servers and tools, it is built on top of systemd, the dublang command-line interface (cli) can be used to install (enable), remove (disable), start and stop services


handlers are executable files, usually lua scripts, that wraps an external tool, run it, and open a TCP server waiting for connection from dublang-nvim

handlers execution are managed by systemd


filters are Lua functions executed each time a code block is evaluated by "CTRL + e"

for example if the SuperCollider code below is evaluated


then the envsubst filter will replace "${HOME}" for "/home/joenio" (in my case), before the code is sent to SuperCollider

filters are executed before the block itself and multiple functions can be combined in a pipeline of filters, each plugin defines a different pipeline but the envsubst is enabled by default in all plugins

filter: envsubst

the filter envsubst expands environment variables in the format ${NAME} before execution, it works like the unix command-line tool envsubst



return ${HOME}

this example will return "/home/joenio" for my user

the envsubst filter is enabled by default for all plugins

example using it to load samples with SuperDirt for Tidal Cycles



filter: confsubst

the filter confsubst expands strings ${config.NAME1.NAME2} by Lua variables defined in the namespace config.NAME1.NAME2 before execution, it works like the filter envsubst but using values defined by Lua instead of using environment variables



return ${config.path.sounds}

this example will return the value for Lua global variable config.path.sounds

the confsubst filter is enabled by default for all plugins

example using it to set pth for MPV videos and images


config.path.mpv = "/home/joenio/videos"


video "dune:01.mp4"


triggers are methods to modify code block evaluation defined on shebang level, added below the shebang line in the format "|trigger [args]"

trigger: |repeat [n]

the trigger repeat schedule the last block execution to be re-executed in a infinite loop every [n] seconds


|repeat 5

return 'hello world'

after the code above be executed it be re-executed every 5 seconds


hooks are points of communication among plugins where events generated by one plugin can be captured by others plugins

one plugin can implement the function hook() to attract others plugins, any plugin implementing the function bite() will bite on the hook executing the function hook() for every connected plugin when code is evaluated by "CTRL + e", for example

see below a diagram with the general overview of hooks and bites functions


plugins can customize the bite() function, but the default code looks like the code below (in Lua)

for i, p in pairs(plugins) do
  if p.hook and p.connected then
    local ok, err = pcall(p.hook, p, ...)

plugins using hooks


reference manual for plugins

home - plugins - tutorials - showcase - history - manual - design