AGAConv - Commodore Amiga CDXL Video Converter

Recent Updates

You can follow release updates on Twitter:

You can see converted CDXL videos running on my Amiga from 1992 in the AGABlaster YouTube channel


This is a retro computing just-for-fun project. AGAConv is a CDXL video converter for Commodore-Amiga computers. It combines some existing tools to convert videos (MP4, etc.) into the CDXL format which can be played with AGABlaster or other CDXL players on an AGA Commodore-Amiga computer. The first Commodore-Amiga computer with the AGA chipset was released in 1992. Commodore went bankrupt in April 1994.

The CDXL format was created by Commodore primarily for the Commodore CDTV, released 1991, to permit playback of video from CD-ROM in the early 1990s. The CDXL format is a simple streaming format, consisting of linear concatenated chunks (packets), each with an uncompressed frame and associated audio data. In addition to the original 12-bit colors, AGAConv also supports 24-bit colors, as supported by Commodore Amiga AGA systems released in 1992+. It also ensures 32-bit padding of CDXL chunks, which can make a difference in video frame rate of up to 50%.

Overview of supported video/audio modes:

AGAConv was tested on Ubuntu 18.04 and on Windows 10 with Microsoft's Ubuntu app/terminal. The generated videos were tested on an Amiga 4000/60 with AGABlaster and Amiga OS 3.9 with original graphics and sound hardware.

Integrated Tools in AGAConv

AGAConv combines several tools to generate a CDXL file via a single command-line interface.

The script agaconv provides command line options such that every conversion can be done via a single command line and eventually calls agaconv-encode to generate a CDXL file that can be played on an Amiga with AGABlaster.


Binary and Open-Source


agaconv 0.9.7 is distributed with a GPL v3 open-source license.

Release Notes

How to Use AGAConv

AGAConv can generate custom CDXL files with 24-bit colors and standard CDXL files with 12-bit colors. All generated CDXL files can be played with AGABlaster without providing any additional command line options. The standard CDXL files can also be played with other CDXL players, such as cdgsxl and ffplay. Other players than AGAConv require additional command line options for speed/resolution settings. AGABlaster does not require any additional command line options for AGAConv generated CDXL files.

By default AGAConv generates videos with 24 frames per second (FPS), 28000 Hz, stereo sound, 320 pixel width, the height scaled to an Amiga screen (to maintain the original aspect ratio), and 256 colors per frame (AGA). Therefore, the easiest way to generate an AGA video is to provide only the input file name and and the output file name (see very first example). In the examples, additional command line options are only used to demonstrate how values different to the default values can be selected. The only required inputs are input and ouput file name.

AGA Custom 24-bit CDXL Conversion Examples

OCS/ECS Custom 24-bit CDXL Conversion Examples

OCS/ECS Standard 12-bit CDXL Conversion Examples (requires AGABlaster 0.9.82 or later)

Here are some examples for generating a standard CDXL video with 12-bit color range which can be played with any CDXL player. However, note that other players than AGAConv will require additional command line options to provide some speed-stetting or they support only one. AGAConv does not require this because it picks up all necessary info from the additional information that AGAConv generates in the CDXL frame header.

AGA Standard 12-bit CDXL Conversion Examples (requires AGABlaster 0.9.82 or later)

Playing AGAConv Generated CDXL videos

There exist several CDXL players. Listed here are only those that were used in testing generated CDXL videos.

AGABlaster (Amiga)

AGABlaster can play every AGAConv generated CDXL video without any additional command line options. It can play standard 12-bit CDXL videos and custom 24-bit CDXL videos. Custom 24-bit CDXL videos give the best quality on AGA systems and can be smaller than standard CDXL videos.

agablaster myvideo.cdxl

ffmpeg's ffplay CDXL mode (on multiple platforms)

ffmpeg's ffplay can play standard 12-bit CDXL videos. To my knowledge there is no way to select the display speed, it is the encoded audio frequency that determines the speed. To get a correct display-speed with ffplay select a frequency of 11025 Hz for mono audio videos. Select 22050 Hz for stereo videos (the different frequency setting is required because of an ffplay bug).

ffplay myvideo.cdxl

cdgsxl (Amiga)

cdgsxl can play standard 12-bit CDXL videos and is a well-known CDXL player on the Amiga. It requires additional command line options to run a CDXL file.

cdgsxl myvideo.cdxl dosxl multipal blit lmbabort xlspeed=NUM where NUM is the number of blocks per second (block=2048 bytes).

AGAConv command line options

Depending on the command line options, agaconv invokes 2-3 tools in the background. It ensures that the command line options between those tools are used consistently. It invokes at least ffmpeg and agaconv-encode. Options for HAM and EHB modes trigger to also invoke ham_convert.

The only required options are INPUTFILE and OUTPUTFILE. All other options are only necessary to select values different to the default options.

INPUTFILEprovide name of input video file (e.g. myvideo.mp4)
OUTPUTFILEprovide name of output CDXL file (e.g. myvideo.cdxl)
--fps=NUMBERspecify number of frames per second in CDXL video (default: 24)
--color-mode=MODEwhere MODE is aga8|aga7|...|aga3|ham8|ham6|ehb|ocs5|ocs4|ocs3 (default: aga8 with 24-bit colors)
--screen-mode=MODEwhere MODE is lores|hires|superhires (default: lores)
--monitor-mode=MODE where MODE is amiga|keep_ratio|fill1080|fill1200 (default: amiga)
The four options use scale factors of 1.15|1.00|1.24|1.37.
--width=NUMBERspecify width of CDXL video (default: 320)
--height=auto|NUMBERThis value is automatically computed from the width and monitor mode. However, if NUMBER is provided it will use exactly this height.
--audio-mode=MODEwhere MODE is mono|stereo (default: stereo)
--frequency=NUMBERspecify audio frequency of converted CDXL video (default: 28000). Maximum supported frequency is 28867 Hz.
--dither=MODE where MODE is none|bayer|fs (default:bayer for OCS/AGA (ffmpeg), fs for HAM6/8, EHB (ham_convert))
--std-cdxlgenerate standard CDXL file with fixed frame size, which can also be played with other CDXL players such as cdgsxl and ffplay. If necessary, AGAConv adjusts the audio frequency to ensure correct audio/video synchronization. This sets a default for FPS=15, Frequency=11025. Above options allow to set different values.
--versionprint agaconv version, copyright info, and license info
--quietno progress output on screen during conversion
--helpprint help text
--help-extraprint additional options (only for testing and developers)

All options have good default values. If only the input file name and output file names are provided, then AGAConv generates an AGA8 24-bit CDXL video with 25 fps, 320 width, the height scaled for Amiga monitors, and 28000Hz stereo audio.
Thus, the shortest command line to generate a CDXL video is: ./agaconv myfile.mp4 myfile.cdxl

Splitting MP4 videos to stay below 2GB or 4GB CDXL file size

FFMpeg can be used to split an MP4 video file into multiple MP4 files. Classic Amiga OS only supports files of up to 4GB file size. The file seek OS functions only work up to 2GB (AGABlaster uses a workaround to play up to 4GB, but will jump to the 2GB mark beyond 2GB). Therefore large MP4 video files may need to be split and converted separately to play each part then on a classic Amiga OS computer.

ffmpeg -fflags +igndts -i MYVIDEO.mp4 -c copy -map 0 -segment_time 00:10:00 -f segment -reset_timestamps 1 OUTPUTVIDEO_%03d.mp4

Above ffmpeg command splits the video MYVIDEO.mp4 into multiple files MYVIDEO_000.mp4 MYVIDEO_001.mp4 ... where each file is 10 minutes long. The option -segment_time 00:10:00 allows to specify the length of each generated file.

For example, an AGA7 video with 320x256 at 25 FPS and 28000Hz needs about 320*256*7/8*25+28000=1820000 bytes per second (and a few extra bytes for the frame header and colors). For AGA8 it's 320*256*25+28000=2076000. Hence, about 2MB per second for a Lores full screen video at 25 FPS. An AGA 1 GB CDXL video can store about 500 seconds, which is about 8 minutes (with some extra room for header and colors). Therefore a 2 GB AGA8 CDXL will be about 16 mins, and a 4 GB CDXL about 32 mins at 25 FPS. Note, for a custom CDXL file, the size can be lower because some frames may be using less than the maximum number of bitplanes. AGAConv 0.9.7 and AGABlaster 0.9.83 support 32-Bit frame numbers.


How It Works

CDXL Conversion Phases

AGAConv encodes a sequence of PNG or IFF files and an 8-bit PCM audio stream into a CDXL video. The tool ffmpeg is used to extract the PNG files for a specified number of frames per second, and it can also extract a PCM audio stream for a specified frequency. The same frame rate and frequency that is used with ffmpeg is also be provided to agaconv-encode. In addition, optional tools can be used to convert frames. For example, ffmpeg cannot convert extracted frames to HAM frames. For this purpose the tool ham_convert is invoked, to generate high quality HAM frames. Therefore there are two possible variants of usage:

  1. AGAConv invokes both tools, ffmpeg and agaconv-encode, and ensures that the options are used consistently between the two tools. This conversion method is very fast (about the original playtime of the video).

    Overview FFMPEG+AGAConv CDXL Conversion (1)
  2. AGAConv invokes three tools, ffmpeg, ham_convert, and agaconv and ensures that the options are used consistently between the three tools. This conversion method takes significantly longer than the above method (by about a factor of 20 or more dependent on the selected modes), but allows more Amiga specific formats, for example HAM8/HAM6/EHB are only supported with ham_convert [agaconv version 0.9.5+].

    Overview FFMPEG+AGAConv CDXL Conversion (2)

Each of the variants allows to specify a number of quality arguments to AGAConv which are used when calling the respective tools.

Installation Instructions (Binary)

AGAConv release 1.0 will simplify the installation by providing a PPA package (this will make it available for all Ubuntu supported platforms). Currently only a manual installation is provided.

EAB forum thread discussing installation and usage issues

Linux/Ubuntu 18.04

  1. Enter the following commands in a terminal to install all required dependencies: (this asks for your password)
    • sudo add-apt-repository universe
    • sudo apt update
    • sudo apt install ffmpeg libpng-dev tar default-jdk
  2. Download agaconv-0.9.7-bin.tgz
  3. Unpack the archive with: tar xvzf agaconv-0.9.7-bin.tgz

You can use agaconv now to convert mp4 videos to CDXL videos by typing ./agaconv myfile.mp4 myfile.cdxl in the terminal. See above for conversion examples.

Windows 10

A Windows native installer is not provided yet. On Windows the only way to install the binary distribution of AGAConv is to install the Microsoft Ubuntu App, then install and run AGAConv in the Ubuntu terminal on Windows. All required command lines for installation are provided, but it's quite clunky to use. It does work though. It's easiest if you copy the original video into the directory where you unpacked agaconv.

  1. Install the Ubuntu App/Terminal on Windows - a good tutorial is here: Installing Ubuntu Terminal on Windows 10
  2. After installation go to your Ubuntu terminal and run the following commands to install dependencies (this asks for your password):
    • sudo add-apt-repository universe
    • sudo apt update
    • sudo apt install ffmpeg libpng-dev tar default-jdk xvfb
  3. Download the agaconv-0.9.7-bin.tgz file to your Windows drive and store it in 'Downloads'.
  4. Go to your Ubuntu terminal and type (note the space and period at the end of the line):
    cp /mnt/c/Downloads/agaconv-0.9.7-bin.tgz .
    This copies the file such that it can be accessed from the Ubuntu terminal.
  5. Now type: tar xvzf agaconv-0.9.7-bin.tgz

You can use agaconv now to convert mp4 videos to CDXL videos by typing ./agaconv myfile.mp4 myfile.cdxl in the terminal. See above for more examples.

Note, in the Ubuntu terminal you can use TAB for auto-complete of file names and directory names, hitting TAB twice lists the entire directory (all matches); CURSOR KEY UP gives the previous command.