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://www.oocities.org/br/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:

 

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:'.

 

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.

 

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.

 

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.

 

centre: <int>

	Same as `center:' (see).

 

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).

 

mod: <int>

	Same as `size:' (see).

 

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).

 

transp: <int>

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

 

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:').

 

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.

 

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.

 

up: <str>

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

 

down: <str>

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

 

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',,

 

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:'.

 

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 (.).

 

undef: <0 or 1>

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

 

chromatic: <0 or 1>

	If 1, generate output in chromatic mode.

 

diatonic: <0 or 1>

	If 1, generate output in diatonic mode.

 

microtonal: <0 or 1>

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

 

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).

 

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.

 

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.

 

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

 

procsag: <0 or 1>

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

 

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).

 

replace: <int>

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

 

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:'.

 

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:'.

 

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:'.

 

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]

 

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

 

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:'.

 

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).

 

inputscl: <str>

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

 

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).

 

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.

 

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.

 

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.

 

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

 

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'.

 

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.

 

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.

 

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.

 

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:'

 

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:'

 

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:'.

 

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.

 

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:').

 

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:'.

 

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).

 

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).

 

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://www.oocities.org/br/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/>

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)