IBN-to-IMT: Converting IntyBASIC songs to tracker format

[+DZ-Jay]

Introducing IBN-to-IMT:  A program to convert music data from IntyBASIC Notation (IBN) to Intellivision Music Tracker format (IMT).

 

Description:

The program will translate a music module composed in IntyBASIC Notation (IBN), into the data format used by the Intellivision Music Tracker (IMT).  The result is an assembly source file with the original song represented in the target format.  The output file includes instrument definitions that attempt to reproduce the IntyBASIC sounds.

 

By default, IBN-to-IMT will produce output to support 6 channels, following the default configuration of the Intellivision Music Tracker.  It will also try to determine automatically the most optimal length of patterns to use, removing duplicate patterns across all channels.

 

The default behaviour can be altered with command line options.

 

How It Works:

The crucial problem that IBN-to-IMT attempts to address is how to identify patterns, and how to determine an optimal pattern length in which to split the song data.  The solution it employs is actually to apply brute-force.

 

First, the program scans the original BASIC source file and identifies all the labels and music player commands, extracting a stream of note events (the song stream) and splitting them into channels.  Any music subroutines encountered via the command "MUSIC GOSUB" are unrolled and included inline as part of the song stream.  Throughout this entire pre-processing step, the volume and active instrument of each channel in the original source is tracked.

 

Then, operating on each extracted channel in turn, the program splits the song stream repeatedly into patterns of various row lengths.  At each split, it attempts to deduplicate re-occurring patterns across all channels, and computes an estimate of the size of the data needed to reproduce it.  When all lengths are tested, the program compares the relative sizes of the data for each iteration, and chooses the smallest one.  This is assumed to be the optimal length with a balance between rows and data size.

 

The selected pattern split is then rendered in the Intellivision Music Tracker (IMT) format by emitting the sequence of reused patterns, the channel patterns, and their individual note event sub-patterns.  Any patterns corresponding to a labeled section in the original, will include a comment with its corresponding label for reference.

 

Caveats:

• You must ensure that the source file contains only song statements in valid IntyBASIC Notation (IBN).
   
• Variable song speed is not supported by the Intellivision Music Tracker.  Therefore, the "MUSIC SPEED" command simply sets the speed for the entire song.
   
• The program works best when the original song is naturally organized into repeating groups of notes or musical passages of the same length.
   
• Because the implementation of the Intellivision Music Tracker synthesizer is different from that of the IntyBASIC music player, the instrument sounds will only be approximations.
   
• The commands "MUSIC STOP" and "MUSIC REPEAT" are interpreted as the end of the song.  Therefore, any following statements will be ignored unless referenced in some other way.
   
• You should take care to ensure that control-flow commands such as "MUSIC JUMP" and "MUSIC GOSUB" follow a coherent and logical flow.  Chaotic jumping around in your song may not translate correctly.
   
• Be very careful when exiting a subroutine prematurely via a "MUSIC JUMP" command.  This may result in unbalanced "GOSUB/RETURN" pairs.
   
• Because pattern extraction occurs independently of label positioning, there is a chance that labels wil not line up with the start of a pattern.  Consequently, determining the backtracking from the target of a "MUSIC JUMP" command may fail.  In such event, the program will default to an end-of-song marker.

 

Known Issues & Limitations:

• Error checking is superficial at best.  (What can I say, I'm an optimist.  And lazy.)
   
• Drum arguments are read and extracted, but completely ignored during processing.
   
• The control-flow command "MUSIC JUMP" is treated in a special way:
  • If it points forward into the song stream, it will skip all notes until that point
  • If it points backwards to a previously encountered label, it will signal the end of the song and set the target as the repeat offset for backtracking at the end of the sequence.
  • If a target pattern cannot be determined for some reason, it will default to the end-of-song marker.
     
• The performance command "MUSIC SPEED" will override the actual speed of the entire song, not just of the following sections.

 

How To Use:

For details on how to use IBN-to-IMT and for a comprehensive description of its features and available options, please see the User's Manual included with the program.

 

Requirements:

IBN-to-IMT is implemented as a Perl script.  Therefore, you need an installation of the Perl programming language in your computer.  On Mac, Unix, or Linux systems, Perl is usually included automatically in the standard operating system distribution.  For Windows PCs, you may need to download one and install it.  There are many distributions out there, most of them free for non-commercial use.  One I've used in the past is ActivePerl from ActiveState.

 

Acknowledgements:

This program would not have any reason to exist if it were not for the fabulous work by Arnauld Chevallier (@Arnauld) and Oscar Toledo (@nanochess), respective authors of the original Intellivision Music Tracker and IntyBASIC.

 

I would also like to thank @Nyuundere and @First Spear for suggesting the idea for this tool, and for providing sample files from their own personal repertoires on which to test.  Most of my initial testing was done on a few sample IBN files I found in this forum, which happen to be published by @First Spear.

 

Download:

IBN-to-IMT is now included as part of the Intellivision Music Tracker distribution package.  You are encouraged to get the latest version of the tracker from its dedicated thread.  Nonetheless, below is the conversion program on its own, along with a copy of the user's manual.

 

• trk-utils.zip
• ibn2imt-manual.txt

 

UPDATES:

• 2021-03-04: Updated attachments to latest version (from trk-distro-r4).

 

Edited March 22, 2022 by DZ-Jay

[+DZ-Jay]

I've updated the first post with the latest version of the IBN-to-IMT tool, taken from the upcoming Tracker 1.5 revision #4, to be released in the coming days.

 

This version includes the following changes:

• Fixed:  Labels of de-dupped patterns were not being kept, and therefore missing from output.
• Fixed:  Instrument definition to simulate IntyBASIC's "Flute" was incorrect (sorry @nanochess).
• Fixed:  Configurable note length was not considered when building sub-patterns list with NPK() directives.
• Fixed:  Removed support for option "--env-repro" (Reproduce IntyBASIC Envelopes), since envelopes now recycle automatically, just like IntyBASIC does (requires revision #4 or higher of the tracker distro).
• Fixed:  Updated instrument envelopes to include only 64 sample points.
• Fixed:  Updated "ibn2imt.pl" documentation.

 

Feedback is welcomed!  Please post any questions, issues, or comments related to the IBN-to-IMT tool in this thread.

 

    -dZ.