MSX CAS Packager

A command line interface (CLI) tool to pack/unpack MSX CAS files


Project maintained by apoloval Hosted on GitHub Pages — Theme by mattgraham

Build Status

MSX CAS Packager

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:

Download binaries

Latest version of MCP is 0.2.0. You will find installation binaries in the following links.

If your operating system is not listed above, please try to build from sources as described below.

Build from sources

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 target/release directory.

How it works

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.

If you have installed from sources, you are responsible to put mcp program 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 mcp easily.

As mentioned above, executing mcp --help will let you to know if mcp is 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.

List package contents

With mcp -l arkanoid.cas (or longer version mcp --list arkanoid.cas), we can see the contents of the arkanoid.cas file.

$ 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:

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.

Add contents to package

With mcp -a myprogram.cas myprog.bin, you can create a new CAS file myprogram.cas that contains the file myprog.bin.

$ mcp -a myprogram.cas myprog.bin
Adding myprog.bin... Done

You can check the contents of the new CAS file with mcp -l.

$ mcp -l myprogram.cas
bin    | myprog |   100 bytes | [0x8000,0x803e]: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 |   100 bytes | [0x8000,0x803e]:0x8000

MCP is able to determine the file type by the file extension with the following criteria:

It is possible to add new files to an existing CAS file.

$ mcp -l myprogram.cas
bin    | myprog |   100 bytes | [0x8000,0x803e]:0x8000

$ mcp -a myprogram.cas foobar.dat
Adding foobar.dat... Done

$ mcp -l myprogram.cas
bin    | myprog |   100 bytes | [0x8000,0x803e]: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 |   100 bytes | [0x8000,0x803e]: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 |   100 bytes | [0x8000,0x803e]:0x8000
custom |        |  6920 bytes |
custom |        | 29648 bytes |
custom |        | 49272 bytes |

Extract package contents

Using mcp -x arkanoid.cas, you can extract the contents of arkanoid.cas 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:

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

Export package to WAV format

Using 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.

Acknowledgements

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.