PSGDump Tool

PSGDump tool is parser and converter for chip tune files. It supports PSG and YM input file formats, focusing on AY/YM chip tunes from ZX Spectrum and Atari ST.
The tool produces text output of notes played and creates multi-track MIDI file.

The main goal of PSGDump tool is to help visualizing the notes played by chip tune rather than trying to reproduce exact same sound and effects. One can use this tool to learn playing favorite chip tunes by keyboard or create arrangements.

Requirements

• Python 3
• Python libraries: lhafile, mido
  • can be installed using pip install lhafile mido

Usage

psgdump.py [-h] -i INPUT [-c CLOCK] [-n N16_FRAMES] [-s START_MIDI_FRAME] [-o OUTPUT]

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        input psg file
  -c CLOCK, --clock CLOCK
                        chip clock (zx - default, ym)
  -n N16_FRAMES, --n16-frames N16_FRAMES
                        number of frames for 1/16 note
  -s START_MIDI_FRAME, --start-midi-frame START_MIDI_FRAME
                        number of start frame, default = 0
  -f FREQ_PERIOD, --freq-period FREQ_PERIOD
                        psg dump frequency (Hz), default = 50
  -o OUTPUT, --output OUTPUT
                        output midi file

Supported input files

PSG file

This is very basic format containing periodic dumps of AY registers. Most of ZX Spectrum AY music files (.ay files) can be converted to PSG file format using Ay_Emul.

Format documentation link

YM file

This format is specific to Atari ST and the tool only supports YM6 files currently.

Following features are supported by notes detection:

• SID voice
• SID sinus voice
• SID buzzer

Note: ym files require -c ym option to set correct clock frequency

Format documentation link

Features

Supported

• Note and noise separation
• Volume control
• Notes played by
  • Envelope generator (specific EG shapes only)
  • SID voice, sinus and buzzer
• Tempo detection (based on user input)
• Tempo MIDI track
• Modulation wheel MIDI events

Not supported

• Automatic clock and period frequency detection
  • for non-default values, user should specify them using -c and -f options
• Digidrum feature of YM6 file format

Text output

PSGDump tool prints to stdout log of processing, including table-formatted, tracker-like log of notes played by AY/YM chip. Example:

FrmID Time      Channel 1         Channel 2         Channel 3
                Note Noise Vol    ....
....
 1920 00:38.20  S          V3   | T          V3   | E          V15M
 1921 00:38.21  S C3   N7  V12  | ====== N7  V12  | ====== N7  V12 
 1922 00:38.22  S D#3  === V14  | T A#4  === V14  | T A1   === V15 
 1923 00:38.23  S          V13  | T          V13  | T E1       V15 
 1924 00:38.24  S          V12  | T          V12  | E C#1      V15M
 1925 00:38.25  S          V11  | T          V11  | E          V15M
 1926 00:38.26  S          V10  | T          V10  | E          V15M
 1927 00:38.27  S          V9   | T          V9   | E          V15M
 1928 00:38.28  S          V8   | T          V8   | E          V15M
 1929 00:38.29  S C3   N3  V7   | ====== N3  V6   | E D#0      V15M
 1930 00:38.30  S D#3  === V11  | T F#4  === V9   | E          V15M
 1931 00:38.31  S          V10  | T          V8   | E          V15M
 1932 00:38.32  S          V9   | T          V7   | E          V15M

• Notes start with "note type" letter, which is T for normal voices, S for SID voice (I for sinus SID, B for SID buzzer) and E for Envelope voice.
• === indicates "stop" of previously played note or noise. It happens when either tone/noise is disabled for a channel or volume is zero.

MIDI output

Separate tracks are created for every AY/YM channel and each voice type. This should differ voice characteristics in arrangements where normal and SID voices are not mixed in one track. Each track uses its own MIDI channel.

SID voices are played by their resulting frequency notes, and original SID effect is not saved. It is up to arranger to restore it using instrument real-time settings.

Initial volume of note is set to AY/YM channel volume. Later volume changes of playing note are supported by key pressure MIDI messages. Key pressure values correspond to changed AY/YM channel volume.

Modulation wheel events are added when note frequency slightly changes staying within the same note value.

Tempo calculation

Tempo can't be detected automatically. User can specify "number of frames for 1/16 note" value to set resulting tempo for MIDI output. The default is 6 frames (125BPM).

The value can be easy determined from text output, one can refer to the rhythm which is usually set by repeating noise notes. In the example above, N7 and N3 repeats after 8 frames, so number of frames for 1/16 note is 8 (94BPM).

Noise channel

For noise channel, 32 notes from C3 (#48) to G5 (#79) are used. Their values are reversed compared to
AY noise period values. For example, C3 note is the lowest noise frequency.

Acknowledge

Some ideas from PSG2MID.c by Marcel de Kogel 1996 were used in this tool.