microabc



=                              MICROABC                              =
=                     Hudson Lacerda (2006-2010)                     =



== INTRODUCTION ==

microabc  is  a free  software  which  generates  macros to  represent
microtonal music in  ABC notation.  It was initially  intended for use
along the preprocessor  abcpp, but now it contains  a simple (yet very
useful) built-in  preprocessor, able  to convert delimited  macros and
just intonation  ratios, 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.

	Examples of standard ABC notation:
```

X:1
T: Variationen Op.31
T: (Theme)
C: A.Schoenberg
M: 3/4
L: 1/8
K:none
z _B _F3_G | _E4 =F2 | z =A =D>^C =G2 | z2 ^G3 =B, | =B,4 =C2 |

X:2
L:1/2
K:C
[V:1] C  G/F/ | E2  ||
[V:2] E, D,   | C,2 ||

```

	Examples of ABC Before Processing (for microabc):
```

X:1
T:JI ratios
L:1/2
K:C
[V:1] [1/1]  [3/2]/[4/3]/ | [5/4]2  ||
[V:2] [5/4,] [9/8,]       | [1/1,]2 ||

X:2
T:Sagittal
L:1/2
K:C
[V:1] [C]   [G]/[F]/ | [E\]2 ||
[V:2] [E\,] [D,]     | [C,]2 ||

```


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

	Example of chromatic mode:
	[0] [1] [2] [3] may become: =C ^C =D ^D

	Example of diatonic mode:
	[0] [1] [2] [3] may become: C D E F

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.

	Examples of microtonal mode:
	[0] [1] [2] [3] (macros) may become: =C ^12/17C _10/17D ^2/17D
	[3/2] [3/2'] (JI ratios) may become: ^5/256G ^5/256g
	[C] [E\] [G] (Sagittal) may become: _5/128C _22/125E _5/256G

Literal mode uses given replacement text strings.

	Example of literal mode:
	[0] [1] [2] [3] may become: "^0"B "^1"B "^2"B "^3"B

The command line options -M  and -P preprocess a given file, replacing
defined macros,  ratios (-J) and  pitches in Sagittal  Notation System
(-S).  In  the music file to  be preprocessed, all  macros, ratios and
Sagittal pitches  must be enclosed between delimiters,  like in [10'],
[C#'/|:2], [3/2], [Aw] or [E\].

There are also commands to  generate equal and linear temperaments, to
import/export Scala tuning  files (*.scl) and to write  into files the
tuning definitions for use by timidity++ or fluidsynth.

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

Software you probably will need:
- abcm2ps-4.3.2 (or newer)
- abcMIDI-2006-01-31 (or newer)
- abcpp-1.3.2 (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

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

 
GO TO INDEX GO TO TOP

==USAGE==

==USAGE== (Command-line options)

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 -J -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 abcm2ps:4 -iinputfile -ooutputfile
```
Command-line  options  override  the  corresponding  values  got  from
inputfile.  There are a few more command line options (-e, -E, -J, -P,
-M, -p, -S) which are described in the following section.


 
GO TO INDEX GO TO TOP

==PREPROCESSOR==

==PREPROCESSOR== (Using microabc to preprocess a file)

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 -J enables the  interpretation and conversion
of JI ratios  when preprocessing. It also activates  the conversion of
user defined common macros. -J0 disables the conversion of JI ratios.

The command  line option -S  controls the Sagittal  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>

A special case is:

	%%microabc: include:snt

which computes and inserts  `%%MIDI snt' instructions according to the
current scale, with no file reading.

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

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

 
GO TO INDEX GO TO TOP

==JI-RATIOS==

==JI-RATIOS== (Syntax for just intonation ratios)

With   the  options   -M  (or   -p)  and   -P,  along   with   -J  (or
`procjiratios:1'),  microabc interprets  ratios  for just  intonation.
The  frequency ratios are  relative to  `basefreq:' (see).  Example of
command line:

	microabc -i- -J -Mjimusic.abp -ojimusicformidi.abc

Valid JI ratios are enclosed between brackets [ and ] (or another pair
of user defined delimiters -- see `delim:').

The format is:

	<n> / <d> [<oct>]

where <n> and  <d> are integers and the optional  parameter <oct> is a
string of octave indicators  (up/down) (see `updown:'). Currently, the
frequency is multiplied  or divided by 2/1 (pure  octave) according to
the octave indicator.

If the format is not  followed, microabc ignores the sequence (it does
not convert it).

Example:
```

X:1
Q:1/4=50
K:C
%%microabc: basefreq: 299
[V:1] [1/1]  [9/16']  [5/4]   [13/16'] [3/8'']4 ||
[V:2] [5/8]  [9/8,]   [1/2]   [13/10,] [5/8]4   || 
[V:3] [1/1,] [15/8,,] [5/3,,] [10/11,] [2/1,,]4 ||

```

Tip:  use the command-line  flag -I  to inspect  the conversion  of JI
ratios.

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

 
GO TO INDEX GO TO TOP

==SAGITTAL==

==SAGITTAL== (Syntax for Sagittal pitches)

The command line options -M (or -p) and -P tell to microabc preprocess
a file, replacing Sagittal pitches if `procsag:' or -S is active.  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).

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

 
GO TO INDEX GO TO TOP

==INPUT==

==INPUT== (microabc definitions file)

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 an  user-given file
	name.

 
GO TO INDEX GO TO TOP

outputfor:

outputfor: <PS or MIDI>

	Select one  of the two blocks of  conditional commands defined
	with FOR_PS:  or FOR_MIDI. Must  be used BEFORE the  blocks in
	the input file.

	ADDITIONALLY:

	Select the  type of output for  Sagittal preprocessing.  Might
	be  useful  to   mix  8th-tone-quantised  and  Sagittal  score
	versions  of a music  (den:4 abcm2ps:4  outputfor:MIDI).  This
	case,  use  den <=  30  to  avoid  conflict between  the  MIDI
	accidentals and the Sagittal accidentals.

	Default is MIDI.

	See: `FOR_PS:' and `FOR_MIDI:'.

 
GO TO INDEX GO TO TOP

FOR_PS:

FOR_PS: <BEGIN or END>

	Enclose a block of  options to be conditionally interpreted or
	ignored according to the output type. The instructions between
	the lines FOR_PS:BEGIN and  FOR_PS:END are only interpreted by
	microabc when `outputfor:PS' (command-line flag -P).

	See also: `FOR_MIDI:' and `outputfor:'.

 
GO TO INDEX GO TO TOP

FOR_MIDI:

FOR_MIDI: <BEGIN or END>

	Enclose a block of  options to be conditionally interpreted or
	ignored according to the output type. The instructions between
	the lines FOR_MIDI:BEGIN and FOR_MIDI:END are only interpreted
	by microabc when `outputfor:MIDI' (command-line flag -M).

	See also: `FOR_PS:' and `outputfor:'.

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

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

	`pcn' sets macro names  as pitch-class numbers.  No aliases or
	replacements should  be defined in the input  file (`pcn' only
	works for microtonal or chromatic modes).

	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

procjiratios:

procjiratios: <0 or 1>

	Turn  on (1)  or off  (0)  the conversion  of just  intonation
	ratios  (when using  command line  option -M,  -p or  -P). The
	conversion only occurs if `procmac:' is active.

 
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 that 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 staff notation):
```
	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.  Use the
	command-line option -I to inspect the approximations.

 
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

fluidsynth:

fluidsynth: <filename or 0>

	Generate a  file <filename> with  the tuning for every  one of
	the 128 MIDI pitches,  to play with the fluidsynth synthesiser
	software.   This  requires  a  `scl:' column  (see).   In  the
	resulting file, pitches are represented as floating midi pitch
	numbers * 100.0.  The range is based on `center:' (see).

	To use  the tuning file, run fluidsynth  with the command-line
	option -f <filename>.

	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.

	If  <int>  is  zero  or  negative  (e.g.   `den:0'),  microabc
	computes  the   best  fraction   to  tune  each   note,  using
	denominators  in  the  range  2-256. Note  that  the  greatest
	possible error is  1/512 of semitone (or 1/256  if we consider
	an interval  between two  quantized pitches), but  the greater
	errors  only occur  in special  cases (for  example:  when the
	frequency  is too close  of that  of the  nearest ABC  note or
	quartertone,  there are  only a  few options  of  fractions to
	approximate it).   If any  quantisation error is  greater than
	1/4096 of  semitone, microabc will show the  amount.  For most
	cases, the error is negligible.

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

	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.

 
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. Here is a trick:

	For a small  number <N> of equal divisions  of octave, setting
	`den:'  to   <N>  will  usually   result  in  a   high  tuning
	precision.    For   example,    use   `den:17'    along   with
	`equaltemp:17'.

	If you  need a  more precise tuning,  you should  generate two
	different  files, one  for abc2midi  (high resolution,  big or
	automatic `den:' value) and the other file 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 ==


	 `.w.´
	 `/8\´
	 / 8 \
	   8
	   °

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

== LINKS ==

microabc
	<http://hudsonlacerda.webs.com>

ABC music notation
	<http://abcnotation.com>
	<http://abc.sourceforge.net>
	<http://abcplus.sourceforge.net>
	<http://hudsonlacerda.webs.com>

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>
	<http://ifdo.ca/~seymour/runabc/abcguide/abc2midi_guide.html>

Sagittal - A Microtonal Notation System
	<http://www.sagittal.org>

Scala - Editor, librarian, and analysis tool for musical tunings
	<http://www.huygens-fokker.org/scala>

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


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

==AUTHOR==

Hudson Flávio Meneses Lacerda
	<mailto:hfmlacerda(a)yahoo.com.br>


GO TO INDEX GO TO TOP

Index

==INPUT== | ==JI-RATIOS== | ==PREPROCESSOR== | ==SAGITTAL== | ==USAGE== | abcm2ps: | afreq: | alias: | aliasabc: | aliassagittal: | basefreq: | center: | centre: | chromatic: | commentmark: | defacc: | delim: | den: | diatonic: | down: | dumbacc: | echo: | equaltemp: | fixupdown: | fluidsynth: | FOR_MIDI: | FOR_PS: | inputscl: | key: | lineartemp: | microtonal: | mod: | modnum: | modnumsep: | name: | outfreq: | outputfor: | procjiratios: | 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:

(64 topics)

GO TO INDEX GO TO TOP