AGAConv - Commodore Amiga CDXL Video Converter

Recent Updates


This is a retro computing just-for-fun project. AGAConv is a CDXL video converter for Commodore-Amiga computers. It combines several exisiting tools to convert videos (MP4, etc.) into the CDXL format which can be played with AGABlaster 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.


agaconv 0.9.5 is distributed with a GPL v3 license.


Installation (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-
  3. Unpack the archive with: tar xvzf agaconv-
    This creates two files: agaconv (bash script) and agaconv-encode (executable AMD64 binary file). It can be run on Intel and AMD machines.

    This also unpacks ham_convert (files from used for HAM/EHB conversions.

You can use agaconv to convert AGA 24-bit color and HAM6/HAM8 videos now. See below for examples and options.

Windows 10

On Windows the easiest way to install AGAConv is to install the Microsoft Ubuntu App, then install and run AGAConv in the Ubuntu terminal on Windows.

  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- 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- .
    This copies the file such that it can be accessed from the Ubuntu terminal.
  5. Now type: tar xvzf agaconv-
    This unpacks the archive and creates two files: agaconv (bash script) and agaconv-encode (executable AMD64 binary file). It can be run on Intel and AMD machines.

    This also unpacks ham_convert (files from used for HAM/EHB conversions.

  6. Note: AgaConv does work in the Windows 10 Ubuntu terminal now, the additional package xvfb is required.

You can use agaconv to convert AGA 24-bit color and HAM6/HAM8 videos now. See below for examples and options.


How to Use AGAConv

AGAConv can convert a sequence of PNG or IFF files and a PCM 8-bit audio stream into a CDXL file. All required data can be extracted with ffmpeg with one single command line. It can generate a custom CDXL file with 24-bit colors (from PNG/IFF and PCM files) and standard CDXL files. All generated CDXL files can be played with AGABlaster without providing any additional command line options (in contrast to the original CDXL players).

AGA Conversion Examples

OCS/ECS Conversion Examples

Video Ratio Issues

Note that different monitor types and monitor modes can give very different display ratios, and hence, the video can be displayed with a quite different width:height ratio. The default setting for --monitor-mode is to keep the ratio the same (keep_ratio). AGAConv automatically determines the correct value for the video height from the user-provided width. This works very well in every emulator, they keep a 1:1 aspect ratio. However, on a flat screen that uses a "fill" mode, the result is different. Therefore there exist options for fill1080 (FullHD with height 1080) and fill1200 (Monitor with height 1200 and fill mode). Monitors can also provide an "Aspect" setting, for which the monitor-mode option aspect can be used (it is using a scale-factor of 1.15). This gives exact results on my flat screen, however, it might be different on other monitors (PAL-squash, NTSC-squash, etc.).

Therefore, it's best to check that the ratio of the width to height for the converted video, when displayed, has indeed the correct ratio. For example for a video with original FullHD dimensions (1920x1080) it should also have a 1.78 ratio when displayed with on your Amiga and the respective monitor.

If the AGAConv --monitor-mode settings don't give the desired results, you can also set the scale factor directly with the option --scale-factor=NUMBER. NUMBER is usually a number between 1.00 and 1.40. This only needs to be determined once, it will work then for a video of any size (e.g. cropped, etc.).

A simple rule is: a circle (or square) in the original video, should also be a circle (or square) when displayed with your Amiga on the respective monitor. If not, then the scale factor must be chosen differently.

Video Quality Tricks

If a video has a black stripe on top and bottom because its original aspect ratio is not 1.78, but it's encoded as FullHD video (1920x1080) then it has a black stripe at the top and bottom. These stripes should be cropped to (a) reduce the CDXL size, and (b) improve the conversion quality at the top and bottom border lines. AGAConv 0.9.5+ comes with a little tool 'autocropy' that does this automatically. This tool invokes ffmpeg, determines automatically the height of this black stripe (by playing the video for a few seconds), and re-encodes the video without it. The command takes as arguments the input-video and the output-video. This will reduce CDXL file size and also gives a proper sharp border of the video when displayed - otherwise the border becomes blurry, because the colors get mixed-up with the black lines during the resize-phase of the video conversion.

Example: ./autocropy myvideo.mp4 myvideo_without_black_stripes_at_top_and_bottom.mp4

Then this re-encoded video can be used with AGAConv. If successful, this reduces the height of the video, reduces the size of the final CDXL video. For example a video with aspect ratio of 2.35 that was encoded as FullHD video (by adding black stripes at top and bottom), will then indeed have an aspect ratio of 2.35. Since AGAConv by default keeps the ratio of the input video, it will work just fine with this re-encoded video as well. The less data each frame has, the higher can be the FPS, therefore this can also improve FPS.

AGAConv command line options

Depending on the command line options, agaconv invokes several 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 will also trigger to invoke ham_convert.

--in=FILEprovide name of input video file (e.g. myvideo.mp4)
--out=FILEprovide name of output CDXL file (e.g. myvideo.cdxl)
--statusprint status messages during conversion
--max-fps=NUMBERspecify maximum number of frames per second in CDXL video (default: 25). AGAConv automatically determines the FPS of the original video. If the FPS in the original video is lower than NUMBER, then it uses the original FPS, otherwise it limits the fps to NUMBER.
--fps=NUMBERspecify number of frames per second in CDXL video (independent of the FPS in the original video).
--max-colors=NUMBERspecify the maximum number of colors per frame when extracting with ffmpeg (default: 256; reserves one color for the background color, and one more color because ffmpeg sometimes generates an additional color in the color quantisation)
--color-mode=MODEwhere MODE is normal|ham6|ham8|ehb (default: normal (24-bit colors))
--screen-mode=MODEwhere MODE is lores|hires|superhires (default: lores)
--monitor-mode=MODE where MODE is keep_ratio|aspect|fill1080|fill1200 (default: keep_ratio).
The four options use scale factors of 1.0|1.15|1.24|1.37.
--scale-factor=NUMBER (forces this factor, ignores monitor-mode)
--width=NUMBERspecify width of CDXL video (default: 320)
--height=auto|NUMBERspecify height of CDXL video (default is 'auto'). If a NUMBER is provided it will use exactly that value. If not explicitly specified (=auto), it will compute the height dependent on the option '--monitor-mode'. If none of the options is provided it computes the height to keep the original ratio of the video.
--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.
--ff-dither=MODE where MODE is none|bayer (default:bayer)
--ff-bayer-scale=NUMBER where NUMBER is in range 0..5 (default:4)
--hc-dither=MODE where MODE is none|bayer|fs (default:bayer)
--hc-propagation=NUMBER where NUMBER is in range 0..100 (default:5)
--hc-diversity=NUMBER where NUMBER is in range 0..9 (default: 5), except ehb:0-6 (default 3)), no effect with HAM8.
--hc-ham-quality=NUMBER where NUMBER is in range 1..4: (default: 1 (fastest))
--hc-quant=MODE where MODE is wu|neuquant (default: wu quantisation)
--conversion-tool=TOOLwhere TOOL is ffmpeg|ham_convert (default: ffmpeg). Any color-mode option for HAM/EHB implicitly selects ham_convert as conversion tool. This option only needs to be used when converting AGA6/7/8 frames with ham_convert instead of ffmpeg. All other modes automatically select the only available tool [version 0.9.5+]
--skip-video-extractionreuse with ffmpeg previously extracted PNG frames
--skip-video-conversionreuse with ham_convert previously converted frames
--dry-runcompute and print conversion summary, do not perform actual conversion (good for querying computed target size of video)
--info-file=FILENAMEwrite conversion times for each phase to file FILENAME. The same information is also printed on the screen in the summary at the end of the conversion process.
--no-cleanupdo not remove temporary files
--versionprint agaconv version info and copyright info
--quietno messages during conversion
--helpprint help text

--ff-NAME options are only relevant when ffmpeg is used for frame conversion, --hc-NAME options are only relevant when ham_convert is used. ham_convert is automatically selected when HAM or EHB color mode is requested. All these options have good default values.


Equivalent High Quality GIF Conversion with ffmpeg

Similar to CDXL, a high quality GIF uses 256 colors and a separate color palette in each frame. The following line gives the equivalent GIF file to the generated AGA8 CDXL graphics generated by AGAConv:

ffmpeg -y -i INPUTVIDEO.mp4 -filter_complex "[0:v] fps=24,scale=w=320:h=-1:sws_flags=lanczos:param0=3:sws_dither=none,split [a][b];[a] palettegen=max_colors=256:stats_mode=single:reserve_transparent=false [p];[b][p] paletteuse=new=1:dither=bayer:bayer_scale=4" -q:v 0 OUTPUTVIDEO.gif

Hence, you can use this method to preview how the CDXL will look like on any PC by converting it to a GIF first. The 24-bit RGB colors for all pixels are identical in this GIF, scale=w=320 selects a width of 320 pixel, max_colors=256 sets the maximum number of colors per frame, where each frame has its own color palette (a GIF does not include audio).

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.