ASCL Specification

Learn how to use the ASCL file format, an Ableton-specific extension to the SCL (Scala) format used to store tuning system information. The example below specifies supported directives for reference pitch, note names, note range, and documentation as of Ableton Live 12.1.

! ASCL Specification
!
! ASCL is an Ableton-specific extension to the SCL file format originally developed for
! use with the Scala software to store tuning system information. It is a backwards
! -compatible format where all Ableton-specific extensions are stored in SCL comments
! (whose lines start with !). That means that any ASCL file can be read by software
! capable of reading SCL files.
!
! This specification is itself an ASCL file.
!
! To start with, the file contains a text description, an integer number of notes per
! octave and a list of pitches for each of these notes in either cents (expects a decimal
! number) or integer ratio (e.g. 5/4). These notes are defined in relation to an implied
! but not written zeroeth index. The last number gives the size of the psuedo-octave.
! This format is described in more detail by the official SCL file documentation:
!
!   https://www.huygens-fokker.org/scala/scl_format.html
!
!
An example tuning system to document the ASCL format. If loaded in Live, the short description on this line will be shown in the info text associated with this tuning.
 12
!
 100.0
 200.0
 300.0
 400.0
 500.0
 600.0
 700.0
 800.0
 900.0
 1000.0
 1100.0
 1200.0
!
!
! # General notes for Ableton extensions
!
!   All extended data is stored in comment lines with the prefix @ABL which come after
!   the list of note pitches. All arguments to these definitions are separated by spaces.
!   If you wish your argument to include a space in it, surround it with double-quotes:
!   `"`
!
!   All Scala files that implement Ableton extensions must be in UTF-8 format. A
!   compliant parser for ABL extensions must reject any file that contains Ableton
!   extensions but is not in UTF-8 format.
!
!   Note, if you wish to temporarily disable a directive, simply add an extra ! sign at
!   the beginning of the line, and it will be ignored.
!
!
! # Supported directives:
!
! -- REFERENCE_PITCH - set a reference pitch for this tuning
!     Arguments:
!       Octave number (integer from -2 to 8)
!       Note index within the octave- which note pitch is the frequency set for
!         (positive integer, 0-indexed, less than the number of note pitches in this
!         tuning system. The zeroeth pitch is the implied 0-cent first note pitch.)
!       Frequency (nonzero positive float, in Hz)
!
! @ABL REFERENCE_PITCH 4 9 440.0
!
!
! -- NOTE_NAMES - set default names for the pitch classes in this tuning
!     Arguments:
!      A sequence of note names for every note pitch in the tuning system. The first
!        entry in the sequence applies to the zeroeth note.
!
! @ABL NOTE_NAMES C C♯/D♭ D D♯/E♭ E F F♯/G♭ G G♯/A♭ A A♯/B♭ B
!
!
! ## Note range directives:
!
!   These directives set the range of notes considered valid in the tuning system. You
!   can use one of either of these directives. It is optional to include a NOTE_RANGE
!   directive. It is an error to provide more than one NOTE_RANGE_BY_XXX directive in
!   a file.
!
! -- NOTE_RANGE_BY_FREQUENCY
!     Arguments:
!       Minimum frequency in Hz (float from 4.0 to 21000.0)
!       Maximum frequency in Hz (float from 4.0 to 21000.0, optional)
!
! -- NOTE_RANGE_BY_INDEX
!     Arguments:
!      Minimum octave (-99 to 99)
!      Minimum note pitch index within the octave (integer)
!      Maximum octave (-99 to 99, optional)
!      Maximum note pitch index within the octave (integer, optional)
!
! Without a NOTE_RANGE directive, the notes available in the tuning system will be
! centered around A3 440.0 Hz (MIDI note number 69) unless the tuning system has 12 notes
! per pseudo-octave. All other notes in the tuning system will be calculated accordingly
! on either side: 64 notes below the center point, and 63 notes above it.
!
! If there are 12 notes per pseudo-octave it sets the note closest to A3 440.0 Hz
! to note index 69 in the tuning. The 12 notes per pseudo-octave special case is
! implemented in order for the tuning system note indices to match the default MIDI note
! numbers and thus remain MIDI keyboard compatible by default for 12-note keyboard-based
! tuning systems.
!
! Including a highest note or frequency in a NOTE_RANGE directive is optional
!
! If a NOTE_RANGE directive is used, the first usable note in the tuning system will be
! set to the one specified by the minimum note and octave index (NOTE_RANGE_BY_INDEX), or
! to the first note at or above the minimum frequency (NOTE_RANGE_BY_FREQUENCY).
!
! The maximum playable pitch will be the first note either:
! - 127 steps above the minimum note
! - closest to and below 21kHz
! - the one set as a maximum (NOTE_RANGE_BY_INDEX)
! - or the last note below or equal to the maximum frequency (NOTE_RANGE_BY_FREQUENCY)
!
! If using NOTE_RANGE_BY_INDEX with a tuning where notes are not always in order of
! increasing frequency (non-monotonically increasing), the minimum and/or maximum is
! treated as first and last and may not necessarily correspond to the lowest or
! highest frequency note in the tuning.
!
! NOTE_RANGE_BY_INDEX can only be used if there is an already declared REFERENCE_PITCH
! as the frequency of the minimum (and maximum) pitches are calculated in relation to the
! octave, pitch class index, and frequency given by the reference pitch.
!
! @ABL NOTE_RANGE_BY_FREQUENCY 8.0
!
!
! ## Documentation directives:
!
! -- SOURCE
!     Arguments:
!      Text until end of line
!
! Source text is used to document where a tuning system came from or who maintains the
! file.
!
! @ABL SOURCE Ableton AG
!
! -- LINK
!     Arguments
!      A URL where someone can learn more information about the tuning system. Note that
!      for security reasons, Ableton software may not provide direct access within
!      applications to this link.
!
! @ABL LINK https://www.ableton.com/tuning-system-spec