Koalavideo v06 - a video player for the Commodore 64, created by daddlerTL in 2026
----------------------------------------------------------------------------------

Important: to be able to use Ultimate Audio, the file browser and the autoplay feature with the Ultimate-II(+)(L) cartridge or an Ultimate 64 the firmware version 3.14a or later has to be installed and the Command Interface and Ultimate Audio has to be activated in the settings.
If you want to use Ultimate Audio to play "FPGA" ord "FPGA_UA" files with an Ultimate II(+)(L) cartridge you have to use the audio output of the cartrige. The audio output of the C64 will not putput any sound unless an FPGASID is installed, in which case this will be used.

The motivation for this project was to create a video player for the Commodore 64 that can play a video with sampled original audio with a good video and audio quality. The player uses the REU of the 1541ultimate, the 1541 Ultimate II(+)(L), the Turbo Chameleon 64, the RAD Expansion Unit or similar cartridges that have a compatible REU as a storage device with 16 MiB that holds the video file.

To be able to play a video file the REU of the 1541ultimate (or another compatible cartridge) has to be enabled with the size of 16 MiB, other cartridges have do be disabled to avoid address range conflicts. First load a Koalavideo file (file extension *.reu) into the REU and then start the player. After the player has been started, either the video playback starts immediately or an infoscreen is displayed and the video playback can be started by pressing any key.
With version 04 you can use the file browser that is built in the player to load a video into the REU (1541 Ultimate II(+)(L) cartridge or Ultimate 64 required).

Koalavideo files can be found here at the time of release: 
https://www.dropbox.com/sh/3qm73ydq8q6wwv3/AAA6O76GZjscfWix8UO52UBia?dl=0
(no guarantee for eternal availability)

In the directory "Tools" in the downloaded archive you can find instructions (pdf file) how to create your own video files.

There are already three video players i know for the Commodore 64 with different advantages and disadvantages:
- Nuvieplayer: advantages: best video quality, playlist can be used; disadvantages: short play time, only SID tunes as audio track possible
- BR-TV: advantages: longer play time, sampled audio can be used, high frames rates possible; disadvantages: low video and audio quality, video conversion very time consuming
- avf player for the MMC64: advantages: very long playtime, original audio (mp3); disadvantages: very low video quality, mp3 module required, MMC64 not produced anymore

Koalavideo is somewhere between them regarding play time, video and audio quality. During the development attention was payed to achieve a good audio quality by accurately timing the sample playback between video data transfers and badlines of the VIC-II. The 16 MiB REU was choosen as a storage device because it is built in the wide spread 1541ultimate, 1541 Ultimate II(+)(L), Turbo Chameleon 64, RAD Expansion Unit, the Ultimate 64 and nearly every C64 emulator and provides a low access time and a high and constant data transfer rate. 

At an acceptable frame rate (8.33 fps) you can store a music video with a lenght of about 3.3 minutes. You can create longer videos, but you have to lower the frame rate or add slide shows to the video. For shorter videos you can increase the frame rate up to 16.66 fps (up to 25 fps for 2.35:1 videos).

Koalavideo uses the Mahoney sample format to play the audio track using 8 bit samples. This playback technology was invented by Pex "Mahoney" Tufvesson. 
Alternatively, the linear format (file suffix FPGA or FPGA_UA) can also be used for sound playback, which can be played using Ultimate Audio (included in the Ultimate-II(+)(L) cartridges and the Ultimate 64 (Elite)(II) boards) or an FPGASID.
The Koala format that is used for the video images is a standard graphics format (multicolor 160x200) that originates from the Koalapainter. 
The images are compressed by packing two 4 bit values for the color RAM in each byte and discard the unused borders for the aspect ratios 16:9, 4:3 and 2.35:1.

This is the sixth version of the player that supports Ultimate Audio as an alternative to the SID playback. This is useful if you want to run the player on an Ultimate 64 (Elite)(II) board or a Commodore 64 Ultimate that has no real SID built in. 
The fifth version of the player introduced the support for 2.35:1 videos with a frame rate of up to 25 fps.
Since v04 the player has a built in file browser and the autoplay feature. Both features require a 1541 Ultimate-II(+)(L) cartridge or an Ultimate 64. The Command Interface has to be enabled on those devices to be able to use those features.
Since v02 player controls are available: fast forward, rewind, pause, single frame steps, chapter jumps and stop. More versions are planned that provide additional features like NTSC support, SID music as alternative to the sample sound and maybe some more features. 

The player and the tools are freeware and open source. If you publish an altered version please provide the altered source code and keep my name "daddlerTL" in the files (you can add your own name). 

----------------

The following controls can be used while a video is beeing played:

keyboard: 
  cursor left:  rewind
  cursor right: fast forward
  cursor up:    previous chapter (only available if the video has chapters) or next video *
  cursor down:  next chapter (only available if the video has chapters) or previous video *
  1-0,A-F: jump to chapter 1-16 (only available if the video has chapters and the selected chapter exists)
  P: pause / resume **
  STOP: completely stops the player and allows to change the reu file without having to reload the player or jumps to the file browser *
  Z: single frame back (useful if the player is paused)
  X: single frame forward (useful if the player is paused)
  ,: rewind (faster)
  .: fast forward (faster)
  < (Shift + .): rewind (slower)
  > (Shift + ,): fast forward (slower)
  L: force the video to loop (if autoplay is disabled)
  F1/Shift+F1: change border color **
  +: load and play next video *
  -: load and play previous video *
  C=+F: enables the file browser if available

joystick in port 2:
  left:  rewind
  right: fast forward
  up:    previous chapter (only available if the video has chapters) or previous video *
  down:  next chapter (only available if the video has chapters) or next video *
  fire:  pause / resume, pressing long while pausing: stop player or jump to the file browser *
  left + fire:  rewind (faster)
  right + fire: fast forward (faster)

*  only available if the file browser is enabled
** frequent use of this function may make the video and audio unsynchronised -> in this case a short rewind will resynchronise

Note: the controls are reacting slow when playing videos with a low frame rate, because the keyboard and the joystick is polled only between two frames for technical reasons. When playing such videos you need to hold down the key / joystick until the player is executing the command.

The following controls can be used for the file browser:

keyboard: 
  cursor left:  jumps to the previous page (previous 20 entries)
  cursor right: jumps to the next page (next 20 entries)
  cursor up:    moves cursor up
  cursor down:  moves cursor down
  RETURN: goes to the selected directory or load the selected file into the REU and start the playback
  <-: goes to the parent directory (cd ..)
  F1/F2: changes border color
  F3/F4: changes background color
  F5/F6: changes color of directory entries
  F7/F8: changes color of file entries
  INST/DEL: changes color of the header, footer and the cursor 
  A: enables/disables autoplay 
  I: enables/disables the infoscreen or enables timed automatic start of the playback 
  HOME: jumps to the home directory if set and valid, otherwise goes to the root directory
  SHIFT+HOME: sets the home directory
  B: sets border color during video playback ("default" uses the color specified in the video file) 
  H: display help pages
  S: saves settings (colors, autoplay, infoscreen, home directory) to the flash memory of the 1541 Ultimate II(+)(L) or the Ultimate 64 
  Q: disables the file browser (the player then behaves in the same way as on a device on which no file browser is available)
  U: displays Ultimate-II DOS version
  +: increases the time until the playback is automatically started when an infoscreen ist displayed by 1 second and enables the automatic playback
  -: decreases the time until the playback is automatically started when an infoscreen ist displayed by 1 second and enables the automatic playback

joystick in port 2:
  up:    moves cursor up 
  down:  moves cursor down
  left:  jumps to the previous page (previous 20 entries)
  right: jumps to the next page (next 20 entries)
  fire:  loads and plays selected file or opens selected directory

----------------

Advice for using the autoplay feature and skipping of videos:
In the directory you want to use for automatically playing or skipping videos you should only put Koalavideo files to avoid the player stopping the playback displaying the "NO KOALAVIDEO FILE!" error message.

----------------

Error messages from the file browser:

NO KOALAVIDEO FILE! 
-> the file you selected is not a Video that can be played by the Koalavideo player
-> the error can occur if a buggy firmware is used (I got the error using the Ultimate II+ firmware 3.10j and 3.10h)
VIDEO REQUIRES KOALAVIDEO Vxx!
-> the video you selected requires a later version of the player - Vxx is the required version of the player
ERROR SAVING SETTINGS! 
-> settings could not be saved - this error can occur if the flash memory is full
ERROR LOADING SETTINGS!
-> occurs during program launch if an error occured while loading the settings, e.g. if the config file is corrupted
No config file on flash
-> not a real error, but a note that there is no config file on the flash memory and the default settings were loaded
DIRECTORY EMPTY
-> not a real error, but a note that the directory is empty and therefore no entries can be displayed

----------------

Limits of the file browser:

The maximum number of entries that can be loaded is 255. The maximum amount of data that can be read from a directory is around 8.8 KB. This limit can be reached if a lot of entries with a long name are present in the directory. If one of those limits is reached, the reading from the directory will be stopped and not all entries can be displayed. The entries that were alread read can be used normally. 

----------------

The downloaded archive contains the following files:

- Koalavideo_v06.prg: the actual video player for the Commodore 64
- liesmich.txt: the German readme file with informations about the program
- readme.txt: this file with informations about the program
- Ultimate 64 Ultimate-II(+)(L) settings.pdf: documentation of the required/recommended settings for the Ultimate 64 / Ultimate-II(+)(L) cartridge

directory "Source" (source code and source files):
- subdirectory "Koalavideo v06": source code files of the actual video player for the C64 Studio: open the file "Koalavideo_v06.s64" as "Solution or Project"
- subdirectory "macOS": source code of the Koalavideo v02 REUmaker: can be compiled using the macOS version of QB64 (provided by SkulleateR from the forum 64) + instructions
- Anleitung Erstellung eines Koalavideos.odt: German instructions how to create a Koalavideo (LibreOffice Writer format)
- How to make a Koalavideo.odt: English instructions how to create a Koalavideo (LibreOffice Writer format)
- Koalavideo v01-06 Playlistmaker.bas: the source code of the playlistmaker - can be compiled using QB64
- Koalavideo v06 REUmaker Linux.bas: the source code of the REUmaker (Linux version) - can be compiled using QB64
- Koalavideo v06 REUmaker Windows.bas: the source code of the REUmaker (Windows version) - can be compiled using QB64
- Ultimate 64 Ultimate-II(+)(L) settings.odt: documentation of the required/recommended settings for the Ultimate 64 / Ultimate-II(+)(L) cartridge (LibreOffice Writer format)

directory "Tools" (helper files to create a Koalavideo):
- subdirectory "macOS": tools and instructions to create a Koalavideo using macOS (provided by SkulleateR from the forum64, not tested because I do not have macOS)
- Anleitung Erstellung eines Koalavideos.pdf: German instructions how to create a Koalavideo (pdf format)
- How to make a Koalavideo.pdf: English instructions how to create a Koalavideo (pdf format)
- Koalavideo v01-v06 Infoscreeneditor DE.prg: C64 program (German version) to create or change an infoscreen of an existing Koalavideo file, can be used in an emulator
- Koalavideo v01-v06 Infoscreeneditor EN.prg: C64 program (English version) to create or change an infoscreen of an existing Koalavideo file, can be used in an emulator
- Koalavideo v01-v06 Playlistmaker.exe: program for the automatic creation of a playlist (refer to the instructions how to create a Koalavideo)
- Koalavideo v05-v06 Calculator.ods: file for Libre Office Calc to calculate if a video will fit into the REU at the given length, frame rate and aspect ratio
- Koalavideo v06 REUmaker Linux: program to compile Koala images and a suitable wav file to a Koalavideo file that can be played by the Koalavideo player (Linux version)
- Koalavideo v06 REUmaker Windows.exe: program to compile Koala images and a suitable wav file to a Koalavideo file that can be played by the Koalavideo player (Windows version)
- Project One auto-convert.au3: conversion script for "AutoIt" that automatically converts all bmp files to Koala images using the program "Project One"
- Retropixels batch.bat: batch file for conversion of the bmp files to Koala images using the command line tool "Retropixels"

Note: No separate source code is provided for the Koalavideo v01-v06 Infoscreeneditor because it is a BASIC program. You can view the source code by entering the C64 command LIST.

----------------

version history:

v01: - first working version that just plays the videos and shows an infoscreen if present in the video file

v02: - added player controls: fast forward, rewind, pause, single frame steps and stop (allows loading another reu file without having to reload the player)
     - chapter jumps (only available if chapters are defined in the video file)
     - REUmaker: you can now define chapters and the tool saves inputs for the infoscreen and chapters in a file to allow to use them again without having to reenter everything
       again if you recompile a video
     - instruction how to make a Koalavideo: added faster conversion method using the command line tool "Retropixels" and a batch file

v03: - bugfix: files where the audio uses more than 50% of the REU caused audio errors when fast forwarding, rewinding or chapter jumps were used (reported by youtuber Yucel Bilik)
     - bugfix: player sometimes crashed when it was paused directly after fast forwarding or rewinding
     - bugfix: videos with a playback speed of more than 127 (slideshows) were played too fast
     - videos with a low frame rate now start faster (no more unnecessary long waiting for the first image), also avoids video/audio desync
     - various small modifications to avoid errors with certain video parameters
     - various bugs fixed in the tools REUmaker, Playlistmaker and Infoscreeneditor
     - added tools for creating a Koalavideo using macOS (provided by SkulleateR from the forum 64, not tested because I do not have macOS)

v04: - built in file browser to select the videos to play directly in the player (requires a 1541 Ultimate-II(+)(L) cartridge or an Ultimate 64)
     - autoplay feature: plays all videos in a directory one after the other (requires a 1541 Ultimate-II(+)(L) cartridge or an Ultimate 64)
     - during video playback you can skip to the next or previous video (if the file browser is enabled)
     - the file browser allows disabling the infoscreens or setting a timed automatic playback start (useful when using the autoplay feature)
     - settings made in the file browser can be stored on the flash of the supported devices (they are loaded and applied on the next start of the program)
     - during video playback you can change the color of the border (only temporary for the currently played video)
     - the currently played video can be forced to be played repeatedly (loop) by pressing the L key (only works if autoplay is disabled)
     - color RAM is initialized when the player is started -> avoids wrong text colors if the player is started after colored text was written on the screen
     - the file browser can be disabled prior to running the player by executing the BASIC command POKE 2063,1 or the assembly commands lda #1 and sta $080F
       (useful if the player is launched from another application that already loaded a video into the REU, e.g. from the WiC64)
     - the infoscreens and error message screens can be left by pressing the fire button of the joystick
     - bugfix: audio errors occured while fast forwarding or rewinding if the REU was filled completely with video and audio data

v05: - added 2.35:1 / 21:9 (cinemascope) video format which supports frame rates up to 25 fps
     - bugfix: file browser: garbage could be displayed on screen at the first startup of the player if no config files was stored on the flash of the Ultimate-II(+)(L) cartridge 
     - bugfix: 16:9 videos with looping chapters were not played correctly (reported by youtuber Yucel Bilik)
     - bugfix: moving the joystick diagonally while beeing in the file browser started the player without loading a file
     - REUmaker: added support for wav files in wavex format
     - REUmaker: now displays an error message if the playlist contains image numbers higher than the number of koala images found - 1 (as the image numbers start at 0)
     
v06: - added Ultimate Audio support: this allows a good sound quality on Ultimate 64 boards or Commodore 64 Ultimate devices that do not have a real SID or good 
       replica installed
     - help pages added to the file browser that briefly explain the controls
     - setting for the border colour during video playback added ("default" uses the colour stored in the video file)
     - REU Maker: bug fix: noise could occur at the end of a video when using certain wav files
     - REU Maker: added Linux version
