# microabc

    			       MICROABC
    		      Hudson Lacerda (2006-2007)

    == INTRODUCTION ==

    microabc  is  a free  software  which  generates  macros to  represent
    microtonal music  in ABC notation.  It  is intended for  use along the
    preprocessor abcpp,  although it contains  a simple (yet  very useful)
    built-in preprocessor, able to convert delimited macros and to provide
    support for  Sagittal Notation System.   The preprocessed ABC  code is
    suitable for  abcm2ps and/or abcMIDI.   Other related tools  are Scala
    and timidity++ (for  the programs refered to, see  links below, at the
    end of this file).

    microabc is addressed  to people that use (or are  willing to use) ABC
    notation, and want to do microtonal music with it.

    The  program reads  commands and  data, and  outputs a  list  of macro
    definitions.   Macro  replacements   can   be:  chromatic,   diatonic,
    microtonal or literal.

    Chromatic and diatonic  modes are useful to generate  MIDI files to be
    re-tuned with the program Scala or played by timidity++. They can also
    be   used  to  generate   a  mapping   for  standard   staff  notation
    (tablature-wise approach).

    Microtonal  mode   computes  pitch  quantisation   (approximation)  in
    semitone  fractions   relative  to  the   standard  equal  temperament
    (quarter-tones, eighth-tones,  integer cents, etc.),  using microtonal
    ABC accidentals for abc2midi or abcm2ps.

    Literal mode uses given replacement text strings.

    The command line options -M  and -P preprocess a given file, replacing
    defined macros and pitches in Sagittal Notation System. All macros and
    Sagittal  pitches  must  be   enclosed  between  delimiters,  like  in
    [C#'/|:2].

    There are also commands to  generate equal and linear temperaments, to
    import/export Scala  tuning files (*.scl) and  to write into  a file a
    list of frequencies for use by timidity++.

    microabc is  released under the  GNU General Public License  (GNU GPL)
    <http://www.gnu.org/copyleft/gpl.html>,   and  it   is   available  at
    <http://br.geocities.com/hfmlacerda/index.html#microabc>.

    Software you probably will need:
    - abcpp-1.3.2 (or newer)
    - abcm2ps-4.3.2 (or newer)
    - abcMIDI-2006-01-31 (or newer)

    NOTES:

    1) Due to  the large number  of macros normally needed  for microtonal
    notation, it is strongly recommended to compile abcpp with enough room
    for macros.  For abcpp version  1.3.2, change the line 43 of `abcpp.c'
    to something like this:

    #define MAX_MACROS     512      /* # of #defined macros */

    2) Maybe timidity is configured to use a MIDI Pseudo Reverb, extending
    each  note  for  a  short  duration.  Unfortunately,  this  can  cause
    undesirable side effects when playing MIDI files which use pitchbends.
    One can disable MIDI Pseudo  Reverb with the command-line options like
    -R8 and --reverb=d  , and then use another kind  of reverb effect like
    --reverb=g,<level> or  --reverb=G,<level> , where <level>  is a number
    from 0 to 127. Example:

    	timidity -R8 --reverb=d --reverb=g,50 file.mid

    --------------------------------------------------

    == USAGE ==

    By default, the program reads from stdin and prints to stdout:

    	microabc < inputfile > outputfile

    microabc understands the following command-line flags:

    	-e -E -h -i -I -M -o -p -P -S -t

    The option -h shows a short info and then exits:

    	microabc -h

    There are options  -i and -o for input  and output files respectively,
    but one cannot put spaces before filenames:

    	microabc -iinputfile -ooutputfile

    The option  -i- is to get  no input at all  from file or  stdin -- all
    options should be given from command line.

    The option -o- outputs to stdout (usually redundant, useful along -E).

    Option  -t[<filename>] (see  also command  `testfile:') writes  a test
    file  using  all definitions  (macros)  generated.   If <filename>  is
    omitted, a file named `testfile.abp'  is created. The test file may be
    generated and preprocessed in a single run of microabc:

    	microabc -iInput.txt -tTest.abp -pTest.abp -oTest.abc

    Option  -I  is   used  to  test  the  program   and  inspect  Sagittal
    preprocessing. Shows verbose details on the screen.

    Additional microabc commands can be given from command line:

    	microabc centre:62 < inputfile > outputfile
    	microabc range:-6\ 6 -iinputfile -ooutputfile
    	microabc name:_ABCM2PS_ abcm2ps:4 -iinputfile -ooutputfile

    Command-line  options  override  the  corresponding  values  got  from
    inputfile.  There are a few more command line options (-e, -E, -P, -M,
    -p, -S) which are described in the following section.

    == BUILT-IN PREPROCESSOR ==

    microabc includes  a basic  preprocessor, which can  be used  with the
    option  -M,  -p or  -P  followed  by the  name  of  the  .abp file  to
    preprocess (ABC music  file with macros).  When -M, -p  or -P is used,
    -o  defines the ABC  file to  store the  result of  the preprocessing.
    Macros   defined  via   `echo:',  as   well  as   postscript  commands
    (`abcm2ps:', `psacc:'),  when used, are  written to output  file above
    the  preprocessed  stuff.   Macros  must  have  both  left  and  right
    delimiters.

    Option -M (same as -p) preprocess  the file to render MIDI output with
    abc2midi.

    	microabc -iinputfile -Mabpfile -oabcfile4midi

    Option -P preprocess the file to render PS output.

    	microabc -iinputfile -Pabpfile -oabcfile4ps

    The  difference between  -P  and -M  (or  -p) only  is effective  when
    Sagittal preprocessing is active.

    The command  line option -S  controls the preprocessor (just  like the
    commands `procsag:' and `procmac:'):

    	-S0 disable Sagittal preprocessing.
    	-S1 enable Sagittal and disable common macros preprocessing.
    	-S2 enable both Sagittal and common macros preprocessing.
    	-S is the same as -S1.

    Example:

    	microabc -S -iinputfile -Psagittalabpfile -osagittalabcfile4ps

    When using Sagittal preprocessor to get a score, a abcm2ps format file
    defining the  Sagittal microtonal accidentals is required.   It can be
    `sagittal.fmt'  or `sagittal-pfb.fmt',  included in  microabc package.
    To   get   the   accidentals   in  mixed-symbol   format,   use   also
    `sagittal-mixed.fmt'. To know how to  use format files (.fmt), see the
    documentation of abcm2ps.

    Option -e embeds  the Sagittal font (as PostScript Type  3) to the ABC
    output file, as  well as the support for mixed  notation.  The size of
    the resulting PS files (converted  with abcm2ps) will be large.  It is
    recommended convert it  to PDF to obtain much  smaller files. Be aware
    that, as the  font is embedded as PostScript Type 3  font, it does not
    support  hints,  and therefore  sometimes  may  look  bad on  computer
    screens.   For  high quality  results,  use  the  abcm2ps format  file
    `sagittal-pfb.fmt' instead.

    The flag -E (for `Easy Sagittal') is a combination of these options:

    	-i- -S -e -oEasyFile.abc

    One can change  some microabc parameters by using  commands inside the
    ABC/ABP  file   to  be   preprocessed.   However,  macros   cannot  be
    defined/modified/undefined this way. The syntax is:

    %%microabc: <command> [<parameters> ...]

    For instance, you can change the tuning inside a music piece:

    X:1
    K:C
    %
    T:72-ET
    %%microabc: equaltemp:72
    [Bb][Bb/][Bbf][Bv][Bt][B\][Be][B/][Bf][B^][B#t][B#\][B#]
    %
    T:Just Intonation
    %%microabc: lineartemp:12 2/1 3/2 3
    [Bb][Bb/][Bbf][Bv][Bt][B\][Be][B/][Bf][B^][B#t][B#\][B#]

    IMPORTANT: when preproccessing a file, there is an additional microabc
    command, which is to be used to insert .snt files:

    %%microabc include:<file.snt>

    N.B.: The  contents of the  file inserted with the  command `include:'
    are not preprocessed, it is only  copied to output file. Please use it
    only to  insert .snt  files (`include:' can  be subject to  changes in
    future microabc releases).

    --------------------------------------------------

    == SAGITTAL PITCHES ==

    The command line options -M (or -p) and -P tell to microabc preprocess
    a  file,  replacing Sagittal  pitches.   The  scale  can be  set  with
    `equaltemp:' or  `lineartemp:'.  By default, the  Sagittal pitches are
    interpreted as being in  just intonation.  Currently, Sagittal pitches
    cannot   be   used  in   chords   for   MIDI   output.   Look   inside
    `Sagittal/CharMap2.txt' for accidentals representations in ASCII.

    microabc can process Sagittal pitches according to these rules:

    -- pitches need  to be enclosed between  brackets [ and  ] (or another
    pair of user defined delimiters -- see `delim:').

    	[C] [A] [Ev] [B^]

    -- pitches  must have  a nominal;  nominals can  be A-G  (only capital
    letters).

    	[A] [B] [C] [D] [E] [F] [G]

    -- Sagittal accidentals  can be given  in any of these  ASCII formats:
    long-pure,  short-pure, long-mixed,  short-mixed.   Accidental can  be
    placed after or before the nominal.

    	[A/||\] [A#] [#A] [/||\A] [A#\] [\#A]

    NOTE:  Mixed things  like [#\A]  or [A\#]  may work,  by they  are not
    recommended. Use [A#\] or [\#A] instead.

    -- Additionally,  a Sagittal accidental  can be  given as  its decimal
    code, at left of the nominal.

    	[144D] [144G] [144C]

    -- There are  two ways to indicate  the octave: by  adding modifiers `
    (octave up) or  , (octave down); or by adding  an octave number. Never
    mix the two ways!

    	[C,,] [C,] [C] [C`] [C``]

    -- Octave number can be indicated  at right of nominal and accidental.
    It can be preceded by a colon `:' -- with no space between `:' and the
    number.

    	[D5] [D:5] [D:0] [D1] [D2] [D7] [D:6]

    Middle  [C] is [C5]  (or [C  5] or  [C:5]); this  can be  changed with
    `sagittaloct:', but the pitch  parser will work rather differently. It
    is not recommended  to mix octave numbers with  octave modifiers.  See
    `sagittaloct:' for details.

    NOTE:  Currently,  `aliassagittal:'   and  `replacesagittal:'  do  not
    support octaves as numbers.

    -- Hidden  accidentals in the  score (PostScript)  may be  obtained by
    starting the pitch by a colon `:'.

    	[Ev] [:Ev] [Ev] [:Ev]

    -- Sagittal accents  . and '  are parsed, but ignored  when processing
    Sagittal pitches.

    	[C'/|\..] [G']

    Future releases may support accents for high-precision Sagittal.

    -- Spaces can be  used to separate the items  (accidental, nominal and
    octave).

    	[ C '/|\.. 6 ] [ 144 A 5 ]

    -- There is yet  another way to input Sagittal  pitches: as microtonal
    ABC notes,  using the denominator  as Sagittal code. Numerator  is not
    used.  Also: the  note  in this  format  doesn't need  to be  enclosed
    between delimiters.

    	^/<code><nominal>	e.g. ^/148F or ^/144D
    	_/<code><nominal>	e.g. _/80E  or _/133A

    NOTE:  Pure ABC notes  are not  touched, then  they will  likely sound
    ``wrong'' in  MIDI (because Sagittal  nominals need to be  adjusted to
    the tuning).

    --------------------------------------------------

    == INPUT FORMAT ==

    The input format consists of  a series of lines containing commands or
    scale data (macro names  and aliases, and possibly replacement strings
    or pitch  intervals).  If a line  doesn't have a known  command, it is
    understood as containing scale data.

    ===Comments===

    Either  characters {  or }  causes  the remaining  of the  line to  be
    ignored,  except  for `echo:'  lines  (see).  Comment  markers can  be
    changed with `commentmark:' (see).

    ===Scale data===

    The simplest form  of input is a list of macro  names. By default, the
    first column is  not used, then it will be useful  to number the scale
    degrees.

    The following sample input will  result in a list of macro definitions
    with names like  [A], [B], [C], etc. The  replacement text will depend
    on the  chosen output format.   (By default, the output  is chromatic,
    then: [A] becomes =C (middle C); [B] becomes ^C; [C] becomes =D and so
    on.)

    0  A
    1  B
    2  C
    3  D
    4  E

    Columns  of  scale  data  also  can  contain  equivalent  macro  names
    (aliases),  replacement text  (see the  `replace:' command)  and pitch
    intervals   in   cents   or   frequency   ratios   (see   the   `scl:'
    command). Columns are indexed from zero (first column == column 0).

    ===Commands===

    Commands are instructions  to set output format options.  Below is the
    complete list:

GO TO INDEX GO TO TOP

# commentmark:

    commentmark: <str> [<str>]

    	Define  one or  two  comment  markers.  Default  is  { and  }.
    	microabc only  supports line comments (block  comments are not
    	allowed); so,  comments start with  a marker and span  til the
    	end of the same line.

    	Comments cannot go in a line with the command `commentmark:'.

GO TO INDEX GO TO TOP

# testfile:

    testfile: <str>

    	Write an ABC  test file with name <str>  using all definitions
    	(macros)  generated.   The  command-line option  -t[<str>]  is
    	similar, but will create  a file named `testfile.abp' if <str>
    	is  omitted.  `testfile:'  always requires  a  user-given file
    	name.

GO TO INDEX GO TO TOP

# delim:

    delim:

    	delim: none
    	delim: <str> [<str>]

    	Set the left and right delimiters for macro names. By default,
    	macro names are written between  braces [ and ]. If the second
    	parameter  is   omitted,  macros  will  have   only  the  left
    	delimiter. Use `none' to get macro names without delimiters.

    	NOTE: The built-in preprocessor of microabc requires both left
    	and right delimiters.

GO TO INDEX GO TO TOP

# name:

    name: <str>

    	The given  name is used to  define an empty  macro to identify
    	the file.

    	This macro is useful for conditional code. For example, if you
    	set:
    		name: 19_ET
    	you will can preprocess a code like this:
    		#ifdef 19_ET
    		%%MIDI transpose=-19
    		#else
    		%%MIDI octave=-1
    		#endif

    	Only one `name:' can be used per file.

    	WARNING:    UNFORTUNATELY,    ABCPP-1.3.2    DOESN'T    ACCEPT
    	CONDITIONALS WITH MACROS DEFINED THIS WAY!  YOU HAVE TO RUN IT
    	WITH A -MACRONAME COMMAND LINE OPTION.

GO TO INDEX GO TO TOP

# centre:

    centre: <int>

    	Same as `center:' (see).

GO TO INDEX GO TO TOP

# center:

    center: <int>

    	Set the centre  pitch to <int>.  The default  value is 60, the
    	MIDI  pitch   number  for   middle  C.   When   using  `snt:',
    	`scalakbm:' or `timidity:' (see), this value is used to assign
    	the pitch 0 (centre) to a MIDI pitch.

    	This command is the same as `centre:' (see).

GO TO INDEX GO TO TOP

# mod:

    mod: <int>

    	Same as `size:' (see).

GO TO INDEX GO TO TOP

# size:

    size: <int>

    	Set the modulo (number of  pitches of scale, or scale size) to
    	<int>.

    	Normally,  setting  this  value  is not  needed,  because  the
    	program  counts  the  number   of  scale  data  lines  to  set
    	automatically the value.  Use it  if you want to force another
    	(equal than or  lesser) value. The value 0  cancels a previous
    	forced value.

    	This command is the same as `mod:' (see).

GO TO INDEX GO TO TOP

# transp:

    transp: <int>

    	Transpose to the interval <int> (scale steps).

GO TO INDEX GO TO TOP

# key:

    key: <int>

    	Replace  the   scale  with  its  mode  of   the  degree  (key)
    	<int>. Similar to the command `key' of the program Scala.

    	For instance, if the defined tuning was a Major scale, `key:1'
    	will generate a Dorian  mode, `key:2' will generate a Phrygian
    	mode, an so on.

    	This command is useful to deal with non-equal temperaments.

    	Note  that the scale  is indeed  modified, so  that it  can be
    	saved to  a file with `scala:'.  The  reference frequency (see
    	`basefreq:') is  not changed,  thus there is  no transposition
    	(see `transp:').

GO TO INDEX GO TO TOP

# range:

    range: <min> <max>

    	Set the range  of pitches for macro generation.  The values of
    	<min> and <max> are intervals relative to the center pitch.

    	If <max> is omitted, it is set to <min> plus 127.

GO TO INDEX GO TO TOP

# updown:

    updown: <str> <str>

    	Set the  strings to  append to macro  basic name,  to indicate
    	high and  low pitches  respectively.  The default  strings are
    	the ABC ' (for higher pitches) and , (for lower pitches).

    	`updown:' also set the use of these indications in output.

GO TO INDEX GO TO TOP

# up:

    up: <str>

    	Set individually the first value for `updown:' (see).

GO TO INDEX GO TO TOP

# down:

    down: <str>

    	Set individually the second value for `updown:' (see).

GO TO INDEX GO TO TOP

# fixupdown:

    fixupdown: <0 or 1>

    	If 1, remove redundant module instance symbols. This is useful
    	to set enharmonic pitches from different instances.

    	For example, you can use
    		15/8   B  _C'
    	and let microabc avoid the creation of bad derivations like
    		_C',,

GO TO INDEX GO TO TOP

# modnum:

    modnum: <0 or 1>

    	Use numbers  to indicate the  modulo instance of the  pitch (0
    	for false,  1 for true). If  0, strings are  used instead (see
    	`updown:').

    	See also `modnumsep:'.

GO TO INDEX GO TO TOP

# modnumsep:

    modnumsep: <0 or 1> [<char>]

    	If 1, separate the modulo instance number from the macro basic
    	name (see `modnum:').

    	The optional parameter <char> defines the character to be used
    	as separator. When omitted, the separator is a dot (.).

GO TO INDEX GO TO TOP

# undef:

    undef: <0 or 1>

    	If  1, don't  output macro  replacements.   Definition without
    	replacement string is the abcpp syntax to undefine a macro.

GO TO INDEX GO TO TOP

# chromatic:

    chromatic: <0 or 1>

    	If 1, generate output in chromatic mode.

GO TO INDEX GO TO TOP

# diatonic:

    diatonic: <0 or 1>

    	If 1, generate output in diatonic mode.

GO TO INDEX GO TO TOP

# microtonal:

    microtonal: <0 or 1>

    	If  1, generate  output  in microtonal  mode.   Scale must  be
    	defined with  a command like  `scl:', `inputscl', `equaltemp:'
    	or `lineartemp:'.

GO TO INDEX GO TO TOP

# alias:

    alias:

    	alias: *
    	alias: all
    	alias: <int> [... <int>]

    	Use  the  given  column(s)  of  scale  data  lines  for  macro
    	names. Columns are indexed from 0 (up to 9).

    	`*'  or `all'  select all  columns  for macro  names (this  is
    	useful for chromatic output mode -- see `chromatic:').

    	Default is 1 (second column).

GO TO INDEX GO TO TOP

# aliasabc:

    aliasabc:

    	aliasabc: *
    	aliasabc: all
    	aliasabc: <int> [... <int>]

    	Use  the given  column(s)  as ABC  aliases.   The aliases  are
    	processed  to  result  in  ABC  pitches  with  correct  octave
    	indications.

GO TO INDEX GO TO TOP

# aliassagittal:

    aliassagittal:

    	aliassagittal: *
    	aliassagittal: all
    	aliassagittal: <int> [... <int>]

    	Use the given column(s)  as Sagittal aliases.  The aliases are
    	processed to  result in  Sagittal pitches with  correct octave
    	indications.

GO TO INDEX GO TO TOP

# sagittaloct:

    sagittaloct: <int1> [<int2>]

    	Define the octave index assigned  to the pitch [C] in Sagittal
    	preprocessing.

    	<int1> is the value for the omitted octave number for [C].

    	<int2>  is  the  actual  octave   to  assign  to  [C]  (0  for
    	middle). It can be used to transpose the music by octaves.

    	WARNING:  If   <int1>  is  set  to  0   (zero),  the  built-in
    	preprocessor  will work  in a  rather different  way  than the
    	default,  when interpreting  Sagittal pitches:  octave numbers
    	will  may be  negative; a  hifen/minus (-)  will  be primarily
    	interpreted as  negative signal for octave  number (instead of
    	Wilson's minus accidental); and  a dot (.)  followed by octave
    	number is ignored as a  separator (instead of a Sagittal grave
    	accent).

    	Default values: 5 0

GO TO INDEX GO TO TOP

# procsag:

    procsag: <0 or 1>

    	Turn  on (1)  or off  (0) the  conversion of  Sagittal pitches
    	(when using command line option -M, -p or -P).

GO TO INDEX GO TO TOP

# procmac:

    procmac: <0 or 1>

    	Turn on (1) or off (0) the conversion of common defined macros
    	(when using command line option -M, -p or -P).

GO TO INDEX GO TO TOP

# replace:

    replace: <int>

    	Use  the   given  column  of   scale  data  lines   for  macro
    	replacement. The output will be in literal mode.

GO TO INDEX GO TO TOP

# replaceupdn:

    replaceupdn: <0 or 1>

    	Append  number  of  module   instance  or  up/down  string  to
    	replacement text when in `replace:' or `replaceabc:' (literal)
    	modes.

    	See also `updown:' and `modnum:'.

GO TO INDEX GO TO TOP

# replaceabc:

    replaceabc: <int> [noaccid]

    	Use  the given column  for ABC  replacement. That  column must
    	have valid ABC pitches (like  ^C ^/C or _b''). The replacement
    	will  have  adjusted   octave  indications  (upper/lower  case
    	letters, appended commas or apostrophes).

    	With the  optional expression `noaccid',  all accidentals will
    	be stripped out of the replacement pitch names. This avoids to
    	print  an accidental  for each  note;  then, you  need to  use
    	`dumbacc:-1'   and   `defacc:'identals   for  printing.    See
    	`dumbacc:' and `defacc:'.

    	See  also: `replace:', `replacesagittal:',  `replaceupdn:' and
    	`replacenominal:'.

GO TO INDEX GO TO TOP

# replacesagittal:

    replacesagittal: <int> [noaccid or visibleaccid]

    	Use the  given column  for Sagittal replacement.   That column
    	must have  valid Sagittal pitches (like ^C  C/|\.,, or F|//|).
    	The   replacement  will   have  adjusted   octave  indications
    	(appended commas or backquotes).

    	With the  optional expression `noaccid',  all accidentals will
    	be invisible.

    	With the  optional expression `visibleaccid',  all accidentals
    	will be visible.

    	See   also:  `replace:',  `replaceabc:',   `replaceupdn:'  and
    	`replacenominal:'.

GO TO INDEX GO TO TOP

# replacenominal:

    replacenominal: <int> <reference pitch>

    	Replace an index number enclosed between square braces with an
    	ABC  or Sagittal  nominal corresponding  to the  index number.
    	Useful to set the pitch positions on non-conventional staves.

    	<int> defines the equivalence interval of the index numbers.

    	<reference pitch>  defines the  pitch referenced by  the index
    	0. It should not use any accidentals.

    	This command is to be  used along with either `replaceabc:' or
    	`replacesagittal:'.

    	Example (use it for a score):

    	alias: 0
    	replaceabc: 1
    	replacenominal: 3 E
    	_0 _[0]
    	 0  [0]
    	^0 ^[0]
    	_1 _[1]
    	 1  [1]
    	^1 ^[1]
    	_2 _[2]
    	 2  [2]
    	^2 ^[2]

GO TO INDEX GO TO TOP

# skip:

    skip: <str>

    	Skip   columns  with   the  text   <str>,  but   maintain  the
    	correspondence of the columns. Default is a dot (.).

    	Example:

    	{A tuning by Norbert L. Oldani, from the `Scala' collection}
    	scl: 3
    	alias: 1 2
    	sclmod: 2/1
    	0   C   .    1/1
    	1   C#  Db   25/24
    	2   D   .    9/8
    	3   D#  Eb   32/27
    	4   E   .    5/4
    	5   F   .    4/3
    	6   F#  Gb   45/32
    	7   G	.    3/2
    	8   G#	Ab   25/16
    	9   A	.    5/3
    	10  A#	Bb   16/9
    	11  B	.    15/8

GO TO INDEX GO TO TOP

# scl:

    scl: <int>

    	Use the  column <int> for pitch intervals,  and generate macro
    	replacements  with  ABC   microtonal  accidentals,  except  if
    	`timidity:'  (see)  is  also  used.  With  `timidity:',  macro
    	replacements are chromatic,  and the microtonal information is
    	written to a tuning file for the timidity++ synthesiser.

    	Like in the  Scala *.scl files, pitch intervals  can be either
    	float values in  cents (e.g. 701.955) -- with  decimal dot! --
    	or frequency ratios (e.g.  3/2).  Unlike in Scala, pitch class
    	0 is  not implicit  (use 1/1  or 0.0 for  it), and  the modulo
    	interval (formal octave) is defined by `sclmod:' instead of by
    	the latest pitch class.

    	By  the way,  you  can output  the  defined scale  to a  *.scl
    	file. See `scala:'.

    	See also: `sclmod:', `abcm2ps:', 'snt:' and `timidity:'.

GO TO INDEX GO TO TOP

# sclmod:

    sclmod: <interval>

    	Set  the modulo  interval (formal  octave) when  using `scl:'.
    	<interval> must  be a float in  cents (with decimal  dot) or a
    	frequency ratio. Default is 1200.0 cents == 2/1 (octave).

GO TO INDEX GO TO TOP

# inputscl:

    inputscl: <str>

    	Read scale from the file <str>, in the Scala (*.scl) format.

GO TO INDEX GO TO TOP

# equaltemp:

    equaltemp: <int> [<base_interval>]

    	Generate an  equal tempered scale with <int>  divisions of the
    	<base_interval>. The  later can be a frequency  ratio like 2/1
    	(or simply 2) or a floating value in cents (like 1200.0).

    	Default <base_interval> is 1200.0 cents (octave).

GO TO INDEX GO TO TOP

# lineartemp:

    lineartemp: <int> [<equivalence>] [<generator>] [<countdownwards>]

    	Generate a  linear temperament  with <int> elements,  based on
    	the interval  <generator>, with <countdownwards>  intervals in
    	the  inverse  direction,   and  normalised  according  to  the
    	<equivalence> interval. Similar to Scala `lineartemp' command.
    	[<equivalence>]  and [<generator>]  can be  either  a fraction
    	(like  3/2, 2/1,  or simply  2) or  a floating  value  -- with
    	decimal dot -- in cents.

    	Defaults are for pythagorean just intonation:
    		<equivalence> = 1200.0 cents (octave)
    		<generator>   = 3/2 (pure perfect fifth)
    		<countdownwards> = 0

    	When    preprocessing    Sagittal    pitches,   the    default
    	interpretation  of the  pitches is  just intonation,  which is
    	equivalent to:

    	lineartemp: 12 2/1 3/2 3

    	The command above  can be used to reset  just intonation after
    	using some temperament in a ABC/ABP file.

GO TO INDEX GO TO TOP

# sagittalapprox:

    sagittalapprox: <ndivisions or fifthsize> [<octavesize>]

    	When  converting Sagittal  for MIDI  (command-line  options -S
    	-M),  approximate the  every Sagittal  pitches to  the nearest
    	pitch in the scale  in use (defined with `scl:', `equaltemp:',
    	`lineartemp:' or `inputscl:').

    	Please note  that the direction of this  approximation is from
    	Sagittal to a given scale.

    	The  parameters   indicate  how  to   interpret  the  Sagittal
    	pitches.  They define  the octave  and fifth  sizes  to temper
    	Sagittal nominals and accidentals.

    	If the first argument is an integer, it is taken as the number
    	of equal divisions  to divide the octave. If  not, it is taken
    	as the fifth size in Scala-like format (ratio or cents).

    	The optional  argument <octavesize> is the size  of the formal
    	octave in Scala-like format (ratio or cents).

    	WARNING: Adjust `sagittalbasefreq:' accordingly to `basefreq:'
    	to reduce the errors of the approximation proccess.

GO TO INDEX GO TO TOP

# afreq:

    afreq: <float>

    	Set reference frequency (A -- MIDI pitch 69) to <float> Hertz.

    	This   frequency    is   used   when    computing   microtonal
    	approximations  (see `scl:'  and `basefreq:'),  and  even when
    	quantising  preprocessed Sagittal for  MIDI (if  `abcm2ps:' is
    	used -- uncommon usage).

    	WARNING: Please note that when `abcm2ps:' is used, this is the
    	assumed reference frequency for the player which will PLAY the
    	MIDI file,  or for  the musician which  will READ  a quantised
    	score.  For  instance: `afreq:220'  will generate ABC  code an
    	octave HIGHER  than `afreq:440'. Conversely,  when `abcm2ps:0'
    	or  not used,  `afreq:220' will  generate ABC  code  an octave
    	LOWER  than `afreq:440',  as one  would expect  for generating
    	MIDI files. Use with care.

    	`afreq:'  has no  effect in  chromatic mode  (see `timidity:',
    	`snt:', `chromatic:').   If you want to  transpose your scale,
    	use  `basefreq:'  instead.   For Sagittal  preprocessing,  use
    	`sagittalbasefreq:' (see).

    	Default is 440.0 Hertz.

GO TO INDEX GO TO TOP

# basefreq:

    basefreq: <float> [<int>]

    	Set  the base  frequency  to <float>  Hertz  to compute  pitch
    	frequencies,  when  using  `scl:'.   The second  parameter  is
    	optional, and  assigns the base frequency to  the pitch <int>,
    	instead of to the default pitch 0 (if omitted).

    	Defaults: 261.625565 0

GO TO INDEX GO TO TOP

# sagittalbasefreq:

    sagittalbasefreq: <float> [<nominal>]

    	Set  the referency  frequency  to <float>  Hertz for  Sagittal
    	preprocessing (for MIDI).

    	The optional <nominal> is a letter A, B, C, D, E, F or G which
    	indicates a  Sagittal pitch in the central  octave.  It cannot
    	have any accidentals or octave modifiers.

    	Default: 293.66476792 D (Standard D in 12-tET with A=440Hz)

    	When  <float> is  given  but <nominal>  is omitted,  <nominal>
    	defaults   to  "A".    That   is:  `sagittalbasefreq:440'   is
    	equivalent to `sagittalbasefreq:440 A'.

GO TO INDEX GO TO TOP

# outfreq:

    outfreq: <0 or 1>

    	If  1, output  the  frequencies of  all  pitches when  `scl:',
    	`lineartemp:' or  `equaltemp:' (see) is  used. When `replace:'
    	or `replaceabc:' is used, output frequencies is disabled.

GO TO INDEX GO TO TOP

# snt:

    snt: <filename or 0>

    	When `scl:' is used, generate a file <filename> with a list of
    	commands to set the frequencies  for all MIDI pitches, for use
    	with abc2midi version 1.81  January 31 2006 or newer. abc2midi
    	uses SysEx  Standard MIDI Tuning (SMT) to  set the frequencies
    	within  the output MIDI  files.  Not all MIDI  devices support
    	SMT. timidity++ can play correctly files using SMT.

    	If the parameter is 0, the file generation is cancelled.

GO TO INDEX GO TO TOP

# timidity:

    timidity: <filename or 0>

    	Generate a file <filename>  with the frequencies for every one
    	of the 128  MIDI pitches, to play MIDI  files (or convert from
    	them into  some audio format) with  the timidity++ synthesiser
    	software.   This  requires  a  `scl:' column  (see).   In  the
    	resulting file, frequencies are represented in milihertz.  The
    	range is based on `center:' (see).

    	Only chromatic mapping is supported currently.

    	If the parameter is 0, the file generation is cancelled.

GO TO INDEX GO TO TOP

# scala:

    scala: <filename or 0>

    	Generate  a   tuning  file   according  to  the   Scala  *.scl
    	format. The intervals will be output in cents (all ratios will
    	be converted).   The Scala needs  to be defined with  a `scl:'
    	(see)  column   from  input   or  by  using   `equaltemp:'  or
    	`lineartemp:'.

    	If the parameter is 0, the file generation is cancelled.

    	See also: `scalakbm:'

GO TO INDEX GO TO TOP

# scalakbm:

    scalakbm: <filename or 0>

    	Generate a  mapping file according to the  Scala *.kbm format.
    	The Scala needs to be  defined with a `scl:' (see) column from
    	input or by using `equaltemp:' or `lineartemp:'.

    	Only chromatic mapping is supported currently.

    	If the parameter is 0, the file generation is cancelled.

    	See also: `scala:'

GO TO INDEX GO TO TOP

# den:

    den: <int>

    	Set  the  denominator  for  microtonal  accidentals  (when  in
    	microtonal  mode -- see  `scl:').  Microtonal  accidentals are
    	written (in  ABC) with  semitone fractions. `den:'  allows you
    	have control on the quantisation.

    	For   abc2midi,   there   is   no  explicit   restriction   on
    	denominator. abc2midi  version 1.78 prints a  warning when the
    	denominator  is  not  a power  of  two,  but  this is  a  just
    	inoffensive bug.  The same version of abcmidi uses pitch bends
    	of 7bit to accomplish  microtones in the range -/+2 semitones,
    	so that  the maximum  resolution of the  output MIDI  files is
    	1/32  of semitone.   MIDI  Standard defines  a  pitch bend  of
    	14bit, which gives a precision of 1/4096 of semitone. abc2midi
    	version 1.81 January 31 2006 already uses 14bit accuracy.

    	For abcm2ps, quartertone notation is available; to use it, set
    	the `den:' value to 2. You  can use other values if you create
    	the glyphs  for the respective  accidentals.  There is  a more
    	flexible way  of control,  which is relatively  independent of
    	abc2midi resolution: see `abcm2ps:'.

GO TO INDEX GO TO TOP

# abcm2ps:

    abcm2ps: <int>

    	This  command is  for  use in  microtonal  mode (see  `scl:').

    	NOTE: Please  read the warning  below and also the  warning in
    	the topic `afreq:'.

    	If  <int>  is  non-zero,   set  the  denominator  for  abcm2ps
    	quantised accidentals, and output the corresponding PostScript
    	code  for   accidentals  replacements  (abcm2ps'  %%postscript
    	instructions).

    	If 1, quantisation will be done by semitones.

    	If 2, quantisation will be done by quartertones.

    	If 4 and `psacc:' (see) is non-zero, quantisation will be done
    	by   eighth-tones.   In  this   case,  microabc   will  output
    	PostScript  definitions  for  the  accidentals which  are  not
    	supplied by the program abcm2ps.

    	Other values  are accepted, but the  resulting accidentals are
    	not built  in abcm2ps,  and microabc is  not able  to generate
    	PostScript  definitions for different  microtonal accidentals.
    	Therefore,  the user  should provide  the  required PostScript
    	code to use those accidentals for staff notation.

    	Moreover, the  program abcm2ps only  accepts accidental ratios
    	with numerator and denominator in the range 1-256.  Because of
    	that, if `den:'  is greater than 256, it will  be reset to 256
    	for `abcmps:' microtonal mode.

    	WARNING: With a bit of luck, `abcm2ps:' with den:256 will work
    	fine.   But,  if   abcm2ps  complaints  ``Too  many  microtone
    	accidentals'', please consider the following:

    	The  maximum  number  of  different  ratios  (combinations  of
    	num/den) for  microtonal accidentals actually used  in a tune,
    	for abcm2ps-5.7.1 (since 4.8.8), is 31.

    	To  maximize  the  number  of  microtonal  accidentals  really
    	available (for sure!), use  den:27 .  This will make available
    	up to  62 different microtonal accidentals (31  for sharps and
    	31 for flats), sharing 31 ratios: 27 with denominator 27, plus
    	4   ratios  with   denominator  4,   needed  to   display  the
    	eighth-tones (`abcm2ps:4').

    	However, with  den:27 ,  the precision of  the tuning  will be
    	inside a window  of 3.7 cents.  You might  want to try several
    	`den:' values from 256 down until to find a compromise between
    	tuning precision and a valid  number of accidentals for use by
    	abcm2ps.

    	If you  need a  more precise tuning,  you should  generate two
    	different files, one for abc2midi (high resolution, big `den:'
    	value)  and the other  for abcm2ps  (lesser `den:'  value), or
    	else split the piece in two or more ABC tunes.

    	To produce  microtonal staff notation,  abcm2ps-4.3.2 or newer
    	is required.

GO TO INDEX GO TO TOP

# reduction:

    reduction: <level>

    	If  level is  0, do  not  reduce the  fractions of  microtonal
    	accidentals to simpler ratios when quantising for abcm2ps (see
    	`abcm2ps:').

    	If level is 1, do fraction  reduction from n/m to 1/2 (i.e.  a
    	quartertone)  for  microtonal  accidentals when  (2*n)==m,  in
    	abcm2ps  quantisation,  except   if  `abcm2ps:'  uses  an  odd
    	denominator (see `abcm2ps:').

    	If level is  2, do not generate fractions  n/m where n==m; and
    	do not generate fractions  2*m==n (with n!=2) in ABC microtone
    	accidentals,  except if  `abcm2ps:' uses  an  odd denominator.
    	Conventional  ABC sharps  (^) or  flats  (_), as  well as  the
    	abcm2ps-builtin quartertone accidentals will be used instead.

    	Level 3  is like level 2, except  that quartertone accidentals
    	will be generated whenever  the accidental ratio is equivalent
    	to  1/2 semitone (ignoring  whether `abcm2ps:'  denominator is
    	even or odd).  The effect is that quartertone accidentals will
    	be printed for whatever fraction that express a half semitone.

    	Default is 2.

    	Used in microtonal mode (see `scl:').

GO TO INDEX GO TO TOP

# psacc:

    psacc: <0 or 1>

    	If  1   and  `abcm2ps:'  is  4,   PostScript  definitions  for
    	eighth-tone accidentals are output. This makes abcm2ps able to
    	generate staff notation for  that quantisation. See `scl:' and
    	`abcm2ps:'.

GO TO INDEX GO TO TOP

# dumbacc:

    dumbacc: <-1, 0 or 1>

    	If 1, these ``dumb'' macro definitions for accidentals will be
    	generated,  as  well dumb  macros  with  user given  `defacc:'
    	names:

    	#define [^] ""
    	#define [=] ""
    	#define [_] ""
    	#define [^^] ""
    	#define [__] ""

    	If  -1, the  following macros  will be  created,  besides user
    	given `defacc:' definitions:

    	#define [^] ^
    	#define [=] =
    	#define [_] _
    	#define [^^] ^^
    	#define [__] __

    	If 0, no macros for accidentals will be output.

    	Macro delimiters [ and ] can be changed with `delim:'.
    	See also `replaceabc:' (`noaccid' parameter).

GO TO INDEX GO TO TOP

# defacc:

    defacc: <name> <replacement>

    	Define a  macro for accidental.  The replacement  only will be
    	output if `dumbacc:' is -1. See the rules for `dumbacc:'.

    	See also `replaceabc:' (`noaccid' parameter).

GO TO INDEX GO TO TOP

# echo:

    echo: <text>

    	Print remaining of the line of text to the output file, before
    	the macro definitions. `echo:' lines don't have comments, that
    	is to say: the characters {  and }, as well the text following
    	any of them, are echoed to output file.

    --------------------------------------------------

    == BUGS ==

    - This manual is written in a bad English. Can you help to improve it?

    --------------------------------------------------

    == LINKS ==

    microabc
    	http://br.geocities.com/hfmlacerda/abc/microabc-about.html

    ABC music notation
    	<http://abcnotation.org>
    	<http://abc.sourceforge.net>
    	<http://abcplus.sourceforge.net>
    	<http://geocities.yahoo.com.br/hfmlacerda/>

    abcpp - ABC preprocessor
    	<http://abcplus.sourceforge.net/#abcpp>

    abcm2ps - ABC to PostScript (staff notation)
    	<http://moinejf.free.fr>

    abc2midi - ABC to MIDI (abcMIDI package)
    	<http://ifdo.pugmarks.com/%7Eseymour/runabc/top.html>

    Sagittal - A Microtonal Notation System
    	<http://users.bigpond.net.au/d.keenan/sagittal/>

    Scala - Editor, librarian, and analysis tool for musical tunings
    	<http://www.xs4all.nl/~huygensf/scala/>

    timidity++ - MIDI-to-WAVE converter and player
    	<http://timidity.sourceforge.net/>

    --------------------------------------------------

    ==AUTHOR==

    Hudson Flávio Meneses Lacerda
    	<mailto:hfml(a)brfree.com.br>
    	<http://geocities.yahoo.com.br/hfmlacerda/>

GO TO INDEX GO TO TOP

# Index

abcm2ps: | afreq: | alias: | aliasabc: | aliassagittal: | basefreq: | center: | centre: | chromatic: | commentmark: | defacc: | delim: | den: | diatonic: | down: | dumbacc: | echo: | equaltemp: | fixupdown: | inputscl: | key: | lineartemp: | microtonal: | mod: | modnum: | modnumsep: | name: | outfreq: | procmac: | procsag: | psacc: | range: | reduction: | replace: | replaceabc: | replacenominal: | replacesagittal: | replaceupdn: | sagittalapprox: | sagittalbasefreq: | sagittaloct: | scala: | scalakbm: | scl: | sclmod: | size: | skip: | snt: | testfile: | timidity: | transp: | undef: | up: | updown:

(54 topics)

GO TO INDEX GO TO TOP