PSGPLAY(1)

NAME
psgplay - music player for Atari ST YM2149 SNDH files

SYNOPSIS
psgplay [OPTIONS]... [sndh-file]

DESCRIPTION
PSG play is a music player and emulator for the Atari ST Programmable Sound Generator (PSG) YM2149 and the SNDH file format.

OPTIONS
PSG play accepts the following options. General options:

    -h, --help
        Print the synopsis and exit.

    --version
        Print PSG play version and exit.

    -v, --verbose
        Increase verbosity. May be repeated.

    -i, --info
        Print SNDH file information and exit.
Play options:

    -o, --output=<file>
        Write audio output to the file in WAVE format, or, if ALSA is available, to an ALSA handle if prefixed with "alsa:" (default is "alsa:default"). See NOTES on post-processing audio.

    --start=<[mm:]ss[.ss]>
        Start playing at the given time, given in seconds, or minutes and seconds separated with a colon, and optionally subseconds.

    --stop=<[mm:]ss[.ss]|auto|never>
        Stop playing at the given time, given in seconds, or minutes and seconds separated with a colon, and optionally subseconds, or automatically if the track has a known duration, or never.

    --length=<[mm:]ss[.ss]>
        Play for the given duration, given in seconds, or minutes and seconds separated with a colon, and optionally subseconds.

    -m, --mode=<command|text>
        PSG play defaults to interactive text mode if it is compiled with ALSA for Linux or PortAudio for Linux or Mac OS.

    -t, --track=<number>
        Set track number.

    -f, --frequency=<frequency>
        Set audio frequency in Hz (default 44100).

    --psg-mix=<empiric|linear>
        Empiric (default) mixes the three PSG channels as measured on Atari ST hardware, having a lofi, crunchy, zesty quality; linear sums the channels to produce a cleaner, somewhat insipid sound. See NOTES on combining filters.

    --psg-balance=<A:B:C>
        Set balance between -1 (left) and +1 (right) for PSG channels A, B and C. For example -0.4:0:+0.4 for stereo effect. Default is 0:0:0 for mono. A linear mix of PSG channels is forced. See NOTES on combining filters.

    --psg-volume=<A:B:C>
        Set volume between 0 (off) and +1 (max) for PSG channels A, B and C. For example 0:0:1 to play channel C only. Default is 1:1:1. See NOTES on combining filters.
Disassembly options:

    --disassemble
        Disassemble SNDH file and exit. The disassembly is guided by instruction reachability from the init, play, and exit entry points, to separate executable instructions from data. To deal with interrupt code and self-modifying code, use both the --disassemble and the --trace=cpu options. The disassembly will then print what the processor actually executed in memory, which may have been modified by the program itself, rather than the contents of the SNDH file. The tracing execution length can be set with the --length option.

    --disassemble-header
        Disassemble SNDH file header and exit. This option is the safest choice when updating SNDH metadata, because most of the code is retained with dc.b data bytes for exact reassembly.

    --disassemble-address
        Display address column in disassembly.

    --remake-header
        Remake SNDH file header in disassembly. The can be used to repair broken SNDH metadata such as missing tags, excessive whitespace, etc. It can also be used to update or add new metadata, by editing the produced assembly source code in an editor.
Trace options:

    --trace-output=<file>
        Write trace events to file (default stdout).

    --trace=<device>,...
        Trace device operations of SNDH file and exit. The trace execution length can be set with the --length option. Default is 60 seconds. Devices: all, wch, cpu, reg, dma, psg, snd, mfp, ram, rom, zro. The --trace option can be combined with the --disassemble option. Review the --disassemble option manual section for details. The SNDH file is loaded in memory at address 4000 (in hexadecimal).

COMMAND MODE
PSG play runs in command mode if it is not compiled with ALSA for Linux, or PortAudio for Linux or Mac OS, or the options -o, --output, --start, --stop, --length, --disassemble or --trace are given. Atari ST does not support command mode.

INTERACTIVE TEXT MODE
For Linux and Mac OS, terminal mode and ECMA-48 are used, including support for job control such as process suspension. The currently playing tune is indicated in reverse video. A cursor is shown with >. Keyboard controls:
    escape or q to quit;
    s to stop;
    p or spacebar to toggle pause;
    r or left arrow to rewind 1 second (during pause or play);
    f or right arrow to fast forward 1 second (during pause or play);
    shift-R to toggle repeat tunes;
    shift-S to toggle single or all tunes;
    - to decrease volume;
    + to increase volume;
    1, 2, ..., 9 to play tunes 1, 2, ..., 9;
    < to play the previous tune;
    > to play the next tune;
    k or up arrow to move the cursor up;
    j or down arrow to move the cursor down;
    return to play the tune at the cursor.

RESOURCES
https://github.com/frno7/psgplay

NOTES
PSG play does not yet completely emulate the Atari STE LMC1992 tone (bass and treble) hardware. Multiple filters using the --psg-mix, --psg-balance, or --psg-volume options cannot be combined. The last option given replaces any previous ones. PSG play audio has a DC offset for optimum audio quality, because YM2149 chip music hardware, made in the 1970s, fundamentally generates a unipolar signal which is converted into a bipolar signal. It may be necessary to remove this DC offset with a 2-5 Hz high-pass filter before post-processing.