mt32-pi-control/linux_src/mt32-pi-ctl.readme

#### mt32-pi-ctl 1.0.1a Linux ReadMe ####

mt32-pi-ctl is a control program for the mt32-pi MIDI synthesizer.

Program source, build instructions and ports to different modern and
retro platforms available at https://github.com/gmcn42/mt32-pi-control

The mt32-pi synthesizer lives at https://github.com/dwhinham/mt32-pi


#### Usage Summary ####

mt32-pi-ctl accepts the following parameters:

USAGE: mt32-pi-ctl [OPTIONS]
OPTIONS:
  -h/--help: Print this info.
  -v/--verbose: Be verbose about what is going on.
  -r/--reboot: Reboot the Pi. Will block for a few secs to give it time.
  -p "[CLIENT]:[PORT]" : The ALSA MIDI client and port address to output to (*MANDATORY*).
  -m/--mt32: Switch mt32-pi to MT-32 mode.
  -g/--fluidsynth: Switch mt32-pi to FluidSynth mode.
  -b/--romset [old, new, cm32l]: Switch MT-32 romset.
  -s/--soundfont [NUMBER]: Set FluidSynth SoundFont.
  -S/--mt32-rstereo [0, 1]: Enable/disable MT-32 reversed stereo.
  --mt32-reset: Send an MT-32 reset SysEx message.
  --gm-reset: Send a GM reset SysEx message.
  --gs-reset: Send a GS reset SysEx message.
  -t/--mt32-txt "Some text": Send an MT-32 text display SysEx.
  -T/--sc55-txt "Some text": Send an SC-55 text display SysEx.
  -P/--sc55-bmp FILE.BMP: Display a 16x16 1bpp BMP on the screen. (SC-55 SysEx)
  -X/--sc55-btxt "SomeText": Display a string on the screen as a Bitmap. (SC-55) 
  -N/--negative: Reverse image color. Use with '-P/--sc55-bmp'.
  -M/--midi "C0 01 C0 DE": Send a list of custom MIDI bytes.
  -Y/--syx file.syx : Send the contents of a SYX-file.

You may specify multiple options, i.e. mt32-pi-ctl -m -t "Hello, World!" will
first send the MT-32 mode command and then the screen text.

### smart option completion ####

Since version 1.0.1a, the Linux version of mt32-pi-ctl also comes with command completion
scripts for bash, fish, and zsh that will smartly autocomplete (long) options, romsets, filenames
and, if aplaymidi is in your PATH, even available MIDI ports.

Examples for bash:

  $ mt32-pi-ctl -p <TAB><TAB>
    14:0  28:0

  $ mt32-pi-ctl -p 28:0 --mt<TAB><TAB>
    --mt32  --mt32-reset --mt32-rstereo --mt32-txt

  $ mt32-pi-ctl -p 28:0 --romset <TAB><TAB>
    cm32l  new  old

For this to work mt32-pi-ctl must be in your PATH, e.g. in /usr/local/bin and you need to copy the
completion scripts in linux_src/completion_scripts/ to some special folders so your shell can find
them automatically. The folders may be distro-specific but the ones below should work for
Debian/Ubuntu at the very least. If in doubt, consult your distro's documentation.

Note that you need aplaymidi installed if you want autocompletion to show you available MIDI output
ports for the -p option. On most distros---including Debian, Ubuntu, and Arch---the package you need
is called alsa-utils.

## bash completion script ##

On modern Debian/Ubuntu systems, install the script using
  sudo cp linux_src/completion_scripts/mt32-pi-ctl.bash /usr/share/bash-completion/completions/mt32-pi-ctl

On other or older distros, the bash completion script may need to go to /etc/bash_completion.d/mt32-pi-ctl
instead.

Alternatively you can add the line
  source /path/to/mt32-pi-ctl.bash
to your .bashrc.

After installing, you may need to relogin or reboot.

## fish completion script ###

Install the script using
  sudo cp linux_src/completion_scripts/mt32-pi-ctl.fish /usr/share/fish/vendor_completions.d/mt32-pi-ctl.fish
  
The fish completion script may be located in your home directory under ~/.config/fish/completions
instead, if you prefer.
Once copied, completions should be available in fish immediately.

## zsh completion script ##

Install the script using
  sudo cp linux_src/completion_scripts/mt32-pi-ctl.zsh /usr/local/share/zsh/site-functions/_mt32-pi-ctl

Alternatively you may use any of the directories reported by echo $fpath but note that the script has to
be renamed to _mt32-pi-ctl or zsh won't associate it with the program.
After installing, you may need to relogin or reboot.

#### BSD-License ####

Copyright (C) 2021 Andreas Zdziarstek
with parts
	Copyright (C) 2015-2016 Josuah Demangeon <jd at ssh dot bio> (miniwi font),
	Copyright (C) 2002 Todd C. Miller <Todd.Miller@courtesan.com> (getopt).
	and Copyright (C) 2000 The NetBSD Foundation, Inc. (getopt)

See the individual source files for details.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.