A command line interface (CLI) tool to pack/unpack MSX CAS files
MSX CAS Packager is a command line interface (CLI) tool to manage MSX CAS files. A CAS file is a very common file format used to represent the contents of a MSX cassete tape.
Using MCP you can perform the following actions on a CAS file.
By the way, MCP is free and open source. You only have to obey the terms of the Mozilla Public License, which is basically:
Latest version of MCP is 0.4.0. You will find installation binaries in the GitHub releases section.
If there is no package for your operating system and architecture there, please try to build from sources as described below.
MCP is written in Rust programming language. You will need Rust to be installed in the system to build MCP. The simplest method to do that is to go to the project website and download the latest distribution installer for your platform.
After installing Rust, just go to the top directory of your MCP’s working copy and type:
$ cargo build --release
MCP will be build in the
MCP is a command line utility (CLI), and therefore must be used from a console. If you don’t know how to use a console have a look to the thousand of tutorials available on the Internet and come back later.
In you have installed from binaries, take into account that.
MCP Console. This is just a Windows shell with the apprpriate
%PATH%definition to find the
mcpprogram. Run this launcher and test it by typing
/usr/local/bin. In a typicall installation, this directory should be listed in
PATHenvironment variable, so
mcpcan be executed in your terminal. Please open
mcp --helpto check it works.
If you have installed from sources, you are responsible to put
somewhere in your hard drive and (suggestion) include that directory in your
PATH environment variable. If you do so you will be able to execute
As mentioned above, executing
mcp --help will let you to know if
working fine. But it also presents you the information needed to familiarize
yourself with the command options.
$ mcp --help Usage: mcp -l <cas-file> mcp -a <cas-file> <file>... mcp -x <cas-file> mcp -e <cas-file> <wav-file> mcp --help mcp --version Options: -h, --help Print this message -v, --version Print the mcp version -l, --list Lists the contents of the given CAS file -a, --add Add new files to a given CAS file. If the CAS file does not exist, it is created. -x, --extract Extracts the contents from the given CAS file -e, --export Exports the CAS file into a WAV file
Let’s have a look to each of the commands to see how they work.
mcp -l arkanoid.cas (or longer version
mcp --list arkanoid.cas), we
can see the contents of the
$ mcp -l arkanoid.cas ascii | ark | 256 bytes | bin | ARK | 96 bytes | [0xc000,0xc057]:0xc000 custom | | 32768 bytes |
As you can see, the contents of the file are shown. In this example we have three files in the CAS tape. The first column indicates the file type, which can be one of the following:
binary: a binary file, probably containing a mix of binary code and data. It is typically loaded with
BLOADcommand from the Basic interpreter.
ascii: an ASCII file, probably containing a non-tokenized Basic program. It is typically loaded with
LOADcommand from the Basic interpreter.
basic: a Basic file, containing a tokenized Basic program. It is typically loaded with
CLOADcommand from the Basic interpreter.
custom: custom data, aimed to be loaded by some program in a custom way.
The second column shows the name of the file. The third column shows the length of the file in bytes. The forth column is only shown for binary files, and it contains the memory addresses where the binary data will be placed: start address, end address and begin address.
mcp -a myprogram.cas myprog.bin, you can create a new CAS file
myprogram.cas that contains the file
$ mcp -a myprogram.cas myprog.bin Adding myprog.bin... Done
You can check the contents of the new CAS file with
$ mcp -l myprogram.cas bin | myprog | 96 bytes | [0x8000,0x8057]:0x8000
The bin filename is intentionally shorten than the CAS file. Tape filenames
are limited to six bytes. If your bin file would be
myprogram.bin its name
would be truncated.
$ mcp -a myprogram.cas myprogram.bin Adding myprogram.bin... Warning: filename myprogram.bin is too long, truncating Done $ mcp -l myprogram.cas bin | myprog | 96 bytes | [0x8000,0x8057]:0x8000
MCP is able to determine the file type by the file extension with the following criteria:
file.binis interpreted and stored as binary file. The binary file ID byte (
0xfe) is automatically removed when dumped into the CAS file. Please remember that binary files in cassette do not include it.
file.ascis interpreted and stored as ASCII file. Its contents are automatically padded by MCP with EOF (end-of-file) bytes to have 256-byte aligned blocks required by MSX systems to load the file successfully.
file.basis interpreted and stored as Basic file
It is possible to add new files to an existing CAS file.
$ mcp -l myprogram.cas bin | myprog | 96 bytes | [0x8000,0x8057]:0x8000 $ mcp -a myprogram.cas foobar.dat Adding foobar.dat... Done $ mcp -l myprogram.cas bin | myprog | 96 bytes | [0x8000,0x8057]:0x8000 custom | | 6920 bytes |
Nevertheless, you don’t have to add files one by one. You can specify several files and all them will be added to the CAS file.
$ mcp -l myprogram.cas bin | myprog | 96 bytes | [0x8000,0x8057]:0x8000 custom | | 6920 bytes | $ mcp -a myprogram.cas foobar2.dat foobar3.dat Adding foobar2.dat... Done Adding foobar3.dat... Done $ mcp -l myprogram.cas bin | myprog | 96 bytes | [0x8000,0x8057]:0x8000 custom | | 6920 bytes | custom | | 29648 bytes | custom | | 49272 bytes |
Another relevant thing about adding files to a CAS package is the validation of the input data and the 8-byte alignment.
If we try to add a binary file whose header indicates a file length larger than the actual program bytes, mcp will refuse to add it:
$ mcp -a myprogram.cas prog.bin Adding prog.bin... Error: IO operation failed: invalid binary file header: BEGIN and END addresses reveal a length (123 bytes) larger than program size (122 bytes)
Also, if we try to add weird things such as a tokenized Basic program file of just 1 byte, it will also return an error:
$ mcp -a myprogram.cas prog.bas Adding prog.bas... Error: IO operation failed: invalid basic file: it is too short (1 bytes) to contain a basic program.
Finally, the CAS file format is constrained by design such that any data block must be aligned to an 8-byte boundary. If the length your file, excluding the byte prefix that determines its type in binary and basic formats, is not divisible by eight, mcp will add some padding zeroes at the end until the 8-byte boundary is reached and will show the following warning message:
$ mcp -a myprogram.cas prog.bin Adding prog.bin... Done (padded with 7 bytes!) Warning: some files had lengths that required padding with zeroes to be aligned to 8-byte boundaries. This is a constraint of CAS file format: every data block must start in an offset divisible by 8. For binary files, this means the total length of the file excluding the 0x1F prefix must be 8-byte aligned. For ASCII files, this does not affect you. ASCII files are always aligned to 256-byte boundaries and padded with EOF values (0x1A) needed by MSX BIOS to detect the end of the file. For custom files, the effect is unknown. These files are loaded using custom code. And if padding zeroes affect or not depends on that code. Using the right file sizes is highly recommended to prevent problems. However this is not considered as an error, and your CAS package has been successfully generated.
As the message says, it is recommended to generate your binary files such that their length excluding the 0xFE prefix byte is aligned to 8-byte boundaries.
mcp -x arkanoid.cas, you can extract the contents of
into the working directory.
$ mcp -x arkanoid.cas Extracting ark.asc... Done Extracting ARK.bin... Done Extracting custom.001... Done $ ls ARK.bin ark.asc arkanoid.cas custom.001
The files are extracted using the following criteria:
XXXis a sequence number indicating the relative position of the custom file in the tape.
In case of ASCII files, the trailing EOF bytes are not copied to the target file so you can read the Basic source code as text.
In case of binary files, the leading ID byte (
0xfe) is automatically
prepended to the target file.
$ file ark.asc ark.asc: ASCII text, with CRLF line terminators $ cat ark.asc 10 BLOAD"cas:",R
mcp -e myprogram.cas myprogram.wav you can export the contents of the
tape into a WAV file. The WAV file can be reproduced with your sound card to
load the data into a real MSX hardware using the cassette interface.
$ mcp -e myprogram.cas myprogram.wav Encoding block 0... 371 KiB Encoding block 1... 151 KiB Encoding block 2... 2788 KiB Encoding block 3... 11577 KiB Encoding block 4... 19166 KiB $ file myprogram.wav myprogram.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 8 bit, mono 43200 Hz
The resulting file is ready to be played and make your homebrew programs loadable in your MSX computer.
MCP was coded by porting several code fragments from CAS Tools. Many thanks to Vincent van Dam for his software.
MCP export feature has been tested with several games in OpenMSX emulator. Many thanks to its authors and congratulations for making such a great software.