Synopsys

Usage
    symfonion -V|--version
    symfonion -h|--help
    symfonion --list
    symfonion -p|--play {infile} [-O{midioutport}={regex}]...
    symfonion -c|--compile {infile} [-o {outfile}]
    symfonion -r|--route {midioutport}={midiinport} [-O{midioutport}={regex}] [-I{midiinport}={regex}]

Description

SyMFONION is a music macro language processor whose syntax is based on JSON. It provides a way to describe music works in a structured and object oriented way.

YAML is the recommended input format. The symfonion launcher transparently converts .yaml / .yml files to JSON and runs them through jq` before passing them to the processor. Because YAML is a strict superset of JSON, every JSON example in this documentation and in link:SYNTAX.html[the Syntax reference] is also valid YAML. You can write symfonion files as plain JSON, YAML, or YAML with `jq inheritance directives ($extends, $includes) — the launcher handles all three.

When invoked without specifying any output files, it simply plays the input file(s).

This page documents the command-line arguments for the SyMFONION processor.

If you do not specify any arguments and GUI is available in your environment, a file chooser will be shownand let you choose a symfonion file to be played. SyMFONION will behave as if it is given as a parameter.

Options

-V or --version

Prints the version and the license of this command.

-h or --help

Prints the help of this command.

--list or -l

Lists the available MIDI input and output devices.

--play or -p

Plays the specified file. See also '-O' option.

During playback, a progress line is printed to standard output each time a new measure begins.

Given a YAML file like this:

parts:
  piano:
    channel: 0
  bass:
    channel: 1

sequence:
  - beats: 4/4
    labels: [intro]
    parts:
      - name: piano
        body: C4;E4;G4;C>4
      - name: bass
        body: C3;r4;r4;r4

  - beats: 4/4
    labels: [verse]
    parts:
      - name: piano
        body: F4;A4;C>4;r4
      - name: bass
        body: F3;r4;r4;r4

  - beats: 4/4
    labels: [verse]
    parts:
      - name: piano
        body: G4;B4;D>4;r4
      - name: bass
        body: G3;r4;r4;r4

Playing it produces:

Console
user@host:~/work $ symfonion -p song.yaml
Start playing on port1(1719820123456)
[bar   0] {intro} - piano, bass
[bar   1] {verse} - piano, bass
[bar   2] {verse} - piano, bass
Finished playing.

[bar N] is the zero-based index of the measure in the sequence array of the input file. The {label, …​} section appears only when the measure has a labels field — these strings are defined by the user and are directly searchable in the YAML. The part names after ` - ` are the keys from the parts section that are active in that measure. Measures without labels print without the {…​} section:

[bar   0] - piano, bass

This output makes it easy to correlate what you hear with the corresponding measure in the source file: search for a label name, or count to index N in the sequence array.

--compile or -c

Compiles the specified file to a standard MIDI file. The example command line below compiles the input file 'example2.js' and output the compiled midi file to 'test.mid'.

Console
user@host:~/work $ symfonion -c example2.js -o test.mid
Now compiling...
bar:(0)
    part:<test>[**.|*.|]
bar:(1)
    part:<test>[**.|*.|]
Compilation finished.
user@host:~/work $

see also -o option.

--route or -r {midioutport}={midiinport}

Users can use this option in order to debug regular expressions that are used with -p option. This command will behave like a MIDI patch bay when it is invoked with this option. MIDI devices associated with midioutport and midiinport must be defined by -O and -I options.

-o {output filename}

Unless port names are not defined in the 'parts' section of the input file, compiled midi file is output to the file specified this options. If defined, a '.' followed by a port name will be inserted before the last '.' in the output file name. And if there are more than one ports are used, each port generates its corresponding output file in the same manner.

If this option is not given, this command behave as if a filename 'a.midi' is given.

-O {midioutport}={regex}

This option is used with -p (play) and -r (route) option and assigns the MIDI device to the MIDI-out port name. Port name is defined by "port" attribute in "parts" section or by -r option.

-I {midiinport}={regex}

This option is used with -r (route) option and assigns the MIDI device to the MIDI-in port name. MIDI-in port name is defined by -r option.

Reporting bugs

Issue tracker: https://github.com/dakusui/symfonion/issues

Author

Written by Hiroshi Ukai

See also

Copyright 2013 Hiroshi Ukai.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.