Import / Export

I/O Base Class

All import and export of music formats is performed by classes that inherit from the chiptunesak.base.ChiptuneSAKIO class.

The following methods are available in every I/O class. If the song format is not supported by the individual I/O class, it will either attempt a conversion or raise a chiptunesak.errors.ChiptuneSAKNotImplemented exception. Either is acceptable behavior.

Import functions

class chiptunesak.base.ChiptuneSAKIO[source]
to_chirp(filename, **kwargs)[source]

Imports a file into a ChirpSong

Parameters:
  • filename (str) – filename to import
  • kwargs – Keyword options for the particular I/O class
Returns:

Chirp song
Return type:

ChirpSong object
to_rchirp(filename, **kwargs)[source]

Imports a file into an RChirpSong

Parameters:
  • filename (str) – filename to import
  • kwargs – Keyword options for the particular I/O class
Returns:

RChirp song
Return type:

rchirp.RChirpSong object
to_mchirp(filename, **kwargs)[source]

Imports a file into a ChirpSong

Parameters:
  • filename (str) – filename to import
  • kwargs – Keyword options for the particular I/O class
Returns:

MChirp song
Return type:

MChirpSong object

Export functions

class chiptunesak.base.ChiptuneSAKIO[source]
to_bin(ir_song, **kwargs)[source]

Outputs a song into the desired binary format (which may be ASCII text)

Parameters:
Returns:

binary
Return type:

either str or bytearray, depending on the output
to_file(ir_song, filename, **kwargs)[source]

Writes a song to a file

Parameters:
  • ir_song (ChirpSong, MChirpSong, or RChirpSong) – song to export
  • filename (str) – Name of output file
  • kwargs – Keyword options for the particular I/O class
Returns:

True on success
Return type:

bool

MIDI

class chiptunesak.midi.MIDI[source]

Bases: chiptunesak.base.ChiptuneSAKIO

Import/Export MIDI files to and from Chirp songs.

The Chirp format is most closely tied to the MIDI standard. As a result, conversion between MIDI files and ChirpSong objects is one of the most common ways to import and export music using the ChiptuneSAK framework.

The MIDI class does not implement the standard to_bin() method because it uses the mido library to process low-level midi messages, and mido only deals with MIDI files.

The Chirp framework can import both MIDI type 0 and type 1 files. It will only write MIDI type 1 files.

to_chirp(filename, **kwargs)[source]

Import a midi file to Chirp format

Parameters:
  • filename (str) – filename to import
  • options –
    • keyswitch (bool) Remove keyswitch notes with midi number <=8 (default True)
    • polyphony (bool) Allow polyphony (removal occurs after any quantization) (default True)
    • quantize (str)
      • ’auto’: automatically determines required quantization
      • ’8’, ‘16’, ‘32’, etc. : quantize to the named duration
Returns:

chirp song
Return type:

ChirpSong
to_file(song, filename, **kwargs)[source]

Exports a ChirpSong to a midi file.

Parameters:
  • song (chirpSong) – chirp song
  • filename (str) – filename for export
Returns:

True on success
Return type:

bool

SID

class chiptunesak.sid.SID[source]

Bases: chiptunesak.base.ChiptuneSAKIO

Parses and imports SIDs into RChirp using 6502/6510 emulation with a thin C64 layer.

This class is the import interface for ChiptuneSAK for SIDs. It runs the SID in the emulator, using the information in the SID header to configure the driver, and captures information from the interaction of the code with the SID chip(s) following init and play calls.

The resulting data can be converted to an RChirpSong object and/or written as a csv file that has a row for each invocation of the play routine. The csv file is useful for diagnosing how the play routine is modifying the SID chip and helps inform choices about the conversion of the SID music to the rchirp format.

to_rchirp(sid_in_filename, **kwargs)[source]

Converts a SID subtune into an RChirpSong

Parameters:
  • sid_in_filename (str) – SID input filename
  • options –
    • subtune (int = 0) - subtune to extract (zero-indexed)
    • vibrato_cents_margin (int = 0) - cents margin to control snapping to previous note
    • tuning (int = CONCERT_A) - tuning to use,
    • seconds (float = 60) - seconds to capture
    • arch (string=’NTSC-C64’) - architecture. Note: overwritten if/when SID headers get parsed
    • gcf_row_reduce (bool = True) - reduce rows via GCF of row-activity gaps
    • create_gate_off_notes (bool = True) - allow new note starts when gate is off
    • assert_gate_on_new_note (bool = True) - True => gate on event in delta rows with new notes
    • always_include_freq (bool = False) - False => freq in delta rows only with new note
    • verbose (bool = True) - print details to stdout
Returns:

SID converted to RChirpSong
Return type:

RChirpSong
to_csv_file(output_filename, **kwargs)[source]

Convert a SID subtune into a CSV file

Each row of the csv file represents one call of the play routine.

Parameters:output_filename (str) – output CSV filename

GoatTracker

class chiptunesak.goat_tracker.GoatTracker[source]

Bases: chiptunesak.base.ChiptuneSAKIO

The IO interface for GoatTracker and GoatTracker Stereo

Supports conversions between RChirp and GoatTracker .sng format

to_bin(rchirp_song, **kwargs)[source]

Convert an RChirpSong into a GoatTracker .sng file format

Parameters:
  • rchirp_song (MChirpSong) – rchirp data
  • options –
    • end_with_repeat (bool) - True if song should repeat when finished
    • max_pattern_len (int) - Maximum pattern length to use. Must be <= 127
    • instruments (list of str) - Instrument names that will be extracted from GT instruments directory
      Note: These instruments are in instrument order, not in voice order! Multiple voices may use the same instrument, or multiple instruments may be on a voice. The instrument numbers are assigned in the order instruments are processed on conversion to RChirp.
Returns:

sng binary file format
Return type:

bytearray
to_file(rchirp_song, filename, **kwargs)[source]

Convert and save an RChirpSong as a GoatTracker sng file

Parameters:
  • rchirp_song (RChirpSong) – rchirp data
  • filename (str) – output path and file name
  • options – see to_bin()
to_rchirp(filename, **kwargs)[source]

Import a GoatTracker sng file to RChirp

Parameters:
  • filename (str) – File name of .sng file
  • options –
    • subtune (int) - The subtune numer to import. Defaults to 0
    • arch (str) - architecture string. Must be one defined in constants.py
Returns:

rchirp song
Return type:

RChirpSong

Lilypond

class chiptunesak.lilypond.Lilypond[source]

Bases: chiptunesak.base.ChiptuneSAKIO

to_bin(mchirp_song, **kwargs)[source]

Exports MChirp to lilypond text

Parameters:
  • mchirp_song (MChirpSong) – song to export
  • options –
    • format (string) - format, either ‘song’ or ‘clip’
    • autosort (bool) - sort tracks from highest to lowest average pitch
    • measures (list) - list of contiguous measures, from one track. Required for ‘clip’ format, ignored otherwise.
Returns:

lilypond text
Return type:

str
to_file(mchirp_song, filename, **kwargs)[source]

Exports MChirp to lilypond source file

Parameters:
  • mchirp_song (MChirpSong) – song to export
  • filename (str) – filename to write
  • options – see to_bin()
Returns:

lilypond text
Return type:

str

C128 BASIC

class chiptunesak.c128_basic.C128Basic[source]

Bases: chiptunesak.base.ChiptuneSAKIO

The IO interface for C128BASIC Supports to_bin() and to_file() conversions from mchirp to C128 BASIC options: format, arch, instruments

to_bin(mchirp_song, **kwargs)[source]

Convert an MChirpSong into a C128 BASIC music program

Parameters:
  • mchirp_song (MChirpSong) – mchirp data
  • options – see to_file()
Returns:

C128 BASIC program
Return type:

str or bytearray
to_file(mchirp_song, filename, **kwargs)[source]

Converts and saves MChirpSong as a C128 BASIC music program

Parameters:
  • mchirp_song (MChirpSong) – mchirp data
  • filename (str) – path and filename
  • options –
    • arch (str) - architecture name (see base for complete list)
    • format (str) - ‘bas’ for BASIC source code or ‘prg’ for prg
    • instruments (list of str) - list of 3 instruments for the three voices (in order).
      • Default is [‘piano’, ‘piano’, ‘piano’]
      • Supports the default C128 BASIC instruments: 0:’piano’, 1:’accordion’, 2:’calliope’, 3:’drum’, 4:’flute’, 5:’guitar’, 6:’harpsichord’, 7:’organ’, 8:’trumpet’, 9:’xylophone
    • tempo_override (int) - override the computed tempo
    • rem_override (string) - use passed string for leading REM statement instead of filename

ML64

class chiptunesak.ml64.ML64[source]

Bases: chiptunesak.base.ChiptuneSAKIO

to_bin(song, **kwargs)[source]

Generates an ML64 string for a song

Parameters:
  • song (ChirpSong or mchirp.MChirpSong) – song
  • options –
    • format (string) - ‘compact’, ‘standard’, or ‘measures’; ‘measures’ requires MChirp; the others convert from Chirp
Returns:

ML64 encoding of song
Return type:

str
to_file(song, filename, **kwargs)[source]

Writes ML64 to a file

Parameters:
Returns:

ML64 encoding of song
Return type:

str