ASCL Specification

! 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. 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
 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, what note pitch are we setting the frequency 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
!
! @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 one of either of these directives. 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 (integer)
!      Maximum octave (-99 to 99, optional)
!      Maximum note pitch index (integer, optional)
!
! Without a NOTE_RANGE directive, the application uses a default center note, the closest
! note in the tuning system to A3 440.Hz (MIDI note number 69) unless the tuning system
! has 12 notes per pseudo-octave, in which case it uses E3 (MIDI note number 64). It then
! adds 64 notes below, and 63 notes above the center note unless limited by the minimum
! allowed frequency (4. Hz), in which case it builds the tuning system up from the first
! allowed note in the tuning system.
!
! It is allowed to provide only a minimum NOTE_RANGE without a maximum. If a NOTE_RANGE
! directive is used and no maximum is provided, the application will set the default
! maximum playable pitch to either the note 127 tuning-system steps above the minimum
! note, or the note closest to and below 21kHz, whichever comes first.
!
! NOTE_RANGE_BY_INDEX can only be used if there is an already a 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 4.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, an application may choose to make this link clickable.
!
! @ABL LINK https://www.ableton.com/tuning-system-spec

Ableton offers these in-depth help and learning resources: