The ANKLANG Manual

The Anklang Project <anklang.testbit.org>

July 2022

Abstract
Manual about usage, installation, and scripting of the Anklang digital synthesizer and music creation software.

1 The ANKLANG Manual

This is the Anklang manual, Anklang is a music synthesis and composition program, released as Free Software under the MPL-2.0.

The manual is structured into sections covering tutorial material, Howto descriptions, Man pages, file formats and conventions, development details with related considerations and an API reference.

It is written in Markdown and contributions are welcome, e.g. as pull requests or via the Anklang issue tracker.

2 Program Installation

2.1 Download and Startup

Ankang can be downloaded as binary package for GNU/Linux from its Github release page:

https://github.com/tim-janik/anklang/releases/

To test bleeding edge versions, "Nightly" builds are also available, but mileage may very with these. In particular stability or file format compatibility can be affected in the nightly versions.

The Debian package (.deb) can be installed with tools like gnome-software or via the command line:

# Install Anklang system wide
sudo apt install Downloads/anklang_[VERSION]_amd64.deb
# Start via system PATH
anklang

The AppImage package can be executed without an installation step. Once downloaded, it needs permissions for execution and can be run right away. This is done for instance as follow:

Of course, the same can also be done via the command line:

# Enable execution of the AppImage
chmod +x ~/Downloads/anklang-[VERSION]-x64.AppImage
# Run Anklang via self contained AppImage
~/Downloads/anklang-[VERSION]-x64.AppImage

2.2 Driver Setup

Once Anklang is started, drivers and other settings can be adjusted in the Preferences. The 'File Menu' in the upper left includes an item to open the 'Preferences' dialog.

Depending on the system, a number of PCM and MIDI devices can be selected here. The "PulseAudio Sound Server" or "Automatic driver selection" should work on most systems out of the box. On systems with Jackd installed, the Jackd sound server needs to be running first:

# Suspend PulseAudio and run Jackd instead
# -r avoids realtime mode which requires special rights
# -d alsa uses the Jackd ALSA backend
pasuspender -- jackd -r -d alsa

The Jackd server should be running now, so in Anklang the "JACK Audio Device" can be selected. To verify Anklang does indeed use Jackd, the setup can be inspected as follows:

# List active Jack ports
jack_lsp
# The list should include 'AnklangSynthEngine'

# Start GUI to control Jackd
qjackctl
# Click on the "Graph" button to show connections
# The graph should include 'AnklangSynthEngine'

3 Manual Pages

3.1 ANKLANG(1)

NAME

anklang - Music composition and modular synthesis application

SYNOPSIS

anklang [OPTIONS] [FILES...]

DESCRIPTION

Anklang is a digital audio synthesis application for live creation and composition of music and other audio material. It is released as free software under the MPL-2.0.

Anklang comes with synthesis devices which can be arranged in tracks and controlled via MIDI input devices or pre-programmed clips which contain MIDI notes.

The Anklang sound engine is a dedicated process which is controlled by a user interface based on web technologies that can be run in a special process (like electron) or modern browsers like firefox(1) or google-chrome(1).

OPTIONS

Anklang supports short and long options which start with two dashes ('-').

--
Stop argument processing, treat remaining arguments as files.
-h, --help
Show a help message about command line usage.
--fatal-warnings
Abort on warnings and failing assertions, useful for test modes.
--check
Execute internal tests and benchmarks.
--disable-randomization
Enable deterministic random numbers for test modes.
-v, --version
Print information about the program version.

SEE ALSO

Anklang Website

4 Anklang Scripting

The functionality of Anklang can be extended by user provided scripts. The scripts are written in Javascript and run as part of the User Interface threads.

Scripts can extend editing functionality or implement new controllers. The exact functions provided by a script are registered at script startup time.

4.1 Reference for ui/host.js

4.1.1 WorkerClip class

class WorkerClip
Ase::Clip proxy

4.1.2 WorkerHost class

class WorkerHost

Global host instance for scripts.

piano_roll_clip()
Create handle for the currently selected clip.
script_name()
Retrieve the file name of the current user script.
script_uuid()
Retrieve the UUID set via use_api().
api_level()
Retrieve numeric API level supported by this runtime.
use_api (api_level, script_uuid)
Request use of API level api_level and provide UUID for controllers.
register (category, label, fun, blurb, params)
Register a script function.