Koalavideo v06 - ein Videoplayer fuer den Commodore 64, erstellt von daddlerTL im Jahr 2026
-------------------------------------------------------------------------------------------

Wichtig: um Ultimate Audio, den Dateibrowser und das Autoplay-Feature mit dem 1541 Ultimate II(+)(L)-Modul oder einem Ultimate 64 nutzen zu können, muss die Firmware Version 3.14a oder höher installiert und das Command Interface und Ultimate Audio in den Einstellungen aktiviert sein.
Möchte man Ultimate Audio zum Abspielen von "FPGA"- oder "FPGA_UA"-Dateien mit einem Ultimate II(+)(L)-Modul nutzen, muss man den Tonausgang des Moduls verwenden. Der Tonausgang des C64 gibt dann keinen Ton aus, es sei denn ein FPGASID ist verbaut, dann wird dieser verwendet.

Die Motivation dieses Projekts war es einen Videoplayer für den Commodore 64 zu erstellen, der ein Video mit gesampleten Originalton abspielen kann und das mit einer möglichst guten Bild- und Tonqualität, der die REU der 1541ultimate, der 1541 Ultimate II(+)(L), des Turbo Chameleon 64, der RAD Expansion Unit oder eines ähnlichen Moduls mit einer kompatiblen REU als 16 MiB großen Datenträger nutzt, in die die Videodatei reingeladen wird.

Um ein Video abzuspielen, muss in der 1541ultimate (oder in einem anderen kompatiblen Modul) die REU mit einer größe von 16 MiB aktiviert sein, andere Cartridges (Module) müssen deaktiviert sein, um Adressbereichskonflikte zu vermeiden. Zunächst lädt man eine Koalavideo-Datei (Dateiendung *.reu) in die REU und startet dann den Player. Daraufhin wird entweder das Video sofort gestartet oder es wird zunächst ein Infoscreen angezeigt und die Videowiedergabe beginnt nach dem Drücken einer beliebigen Taste. 
Mit der Version 04 kann man den im Player eingebauten Dateibrowser nutzen, um ein Video in die REU zu laden (1541 Ultimate II(+)(L)-Modul oder Ultimate 64 erforderlich).

Koalavideo-Dateien können zum Zeitpunkt des Release u.a. hier gefunden werden: 
https://www.dropbox.com/sh/3qm73ydq8q6wwv3/AAA6O76GZjscfWix8UO52UBia?dl=0
(keine Garantie für ewige Verfügbarkeit)

Im Verzeichnis "Tools" des heruntergeladenen Archivs befindet sich eine Anleitung (pdf-Datei) zur Erstellung eigener Videodateien.

Es gibt bisher schon drei mir bekannte Videoplayer für den C64 mit verschiedenen Vor- und Nachteilen:
- Nuvieplayer: Vorteile: bestmögliche Bildqualität, Playlist nutzbar; Nachteile: kurze Spielzeit, nur SID-Tunes als Tonspur möglich
- BR-TV: Vorteile: längere Spielzeit, Samplesound möglich, hohe Framerate möglich; Nachteile: geringe Bild- und Tonqualität, Videokonvertierung sehr aufwändig
- avf-Player für das MMC64: Vorteile: sehr lange Spielzeit, Originalton (mp3); Nachteile: sehr geringe Bildqualität, mp3-Modul für Originalton nötig, MMC64-Modul nicht mehr erhältlich

Koalavideo liegt irgendwo dazwischen was Spielzeit, Bild- und Tonqualität betrifft, wobei bei der Entwicklung besonders auf die Tonqualität geachtet wurde durch sorgfältiges Timing bei der Samplewiedergabe zwischen den Bilddatentransfers und Badlines des VIC-II. Es wurde die 16 MiB REU als Datenträger gewählt, da sie in der weitverbreiteten 1541ultimate, 1541 Ultimate II(+)(L), Turbo Chameleon 64, RAD Expansion Unit, im Ultimate 64 sowie in fast jedem C64-Emulator eingebaut ist und eine geringe Zugriffszeit sowie eine hohe und konstante Datentransferrate bietet. 

Bei akzeptabler Framerate (8,33 fps) kann man ein Musikvideo mit ca. 3,3 Minuten Länge in einer Videodatei unterbringen. Man kann auch längere Videos erstellen, muss dann aber die Framerate reduzieren oder Diashows in das Video einbauen. Bei kürzeren Videos kann man die Framerate auf bis zu 16,66 fps erhöhen (bis zu 25 fps bei 2,35:1-Videos).

Koalavideo nutzt das Mahoney-Sampleformat, um die Tonspur mit 8 Bit-Samples abzuspielen. Diese Abspieltechnologie wurde von Pex "Mahoney" Tufvesson erfunden.
Alternativ kann für die Tonwiedergabe auch das lineare Format (Dateisuffix FPGA oder FPGA_UA) genutzt werden, welches mittels Ultimate Audio (in den Modulen Ultimate-II(+)(L) und den Ultimate 64 (Elite)(II)-Boards enthalten) oder einem FPGASID abgespielt werden kann. 
Das genutzte Koala-Format, das für die Videobilder genutzt wird, ist ein Standardgrafikformat (Multicolor 160x200), welches u.a. vom KoalaPainter genutzt wird. 
Die Einzelbilder werden komprimiert, indem jeweils zwei 4 Bit-Werte des Farb-RAMs in ein Byte gepackt werden und bei den Seitenverhältnissen 16:9, 4:3 und 2,35:1 die ungenutzten Ränder nicht abgespeichert werden.

Dies ist die sechste Version des Players, die als Alternative zur SID-Wiedergabe Ultimate Audio unterstützt. Dies ist vorallem nützlich, wenn man den Player auf einem Ultimate 64 (Elite)(II)-Board oder einem Commodore 64 Ultimate ohne echten SID laufen lassen möchte.
Seit der fünften Version werden 2,35:1-Videos mit einer Framerate von bis zu 25 fps unterstützt. 
Seit der vierten Version gibt es den Dateibrowser und das Autoplayfeature. Für beides wird ein 1541 Ultimate II(+)(L)-Modul oder ein Ultimate 64 benötigt. Das Command Interface muss in den Einstellungen dieser Geräte aktiviert werden, um diese Funktionen nutzen zu können.
Seit der zweiten Version gibt es auch Steuerungsmöglichkeiten: Vorspulen, Zurückspulen, Pause, Einzelbildschritte, Kapitelsprünge und Stop. Geplant sind weitere Versionen mit Zusatzfeatures wie NTSC-Unterstützung, SID-Musik als Alternative zum Samplesound und eventuell weiteren Funktionen.

Der Player und die Tools sind Freeware und Open Source. Wenn du eine modifizierte Version davon veröffentlichst, liefere bitte den geänderten Quellcode mit und lass meinen Name daddlerTL stehen (eigener Name kann hinzugefügt werden). 

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

Folgende Steuerungsmöglichkeiten existieren während der Videowiedergabe:

Tastatur: 
  Cursor links:  Zurückspulen
  Cursor rechts: Vorspulen
  Cursor hoch:   vorheriges Kapitel (nur, wenn das Video Kapitel hat) oder vorheriges Video *
  Cursor runter: nächstes Kapitel (nur, wenn das Video Kapitel hat) oder nächstes Video *
  1-0,A-F: Sprung zu Kapitel 1-16 (nur, wenn das Video Kapitel hat und das gewählte Kapitel existiert)
  P: Pause / Fortsetzen **
  STOP: hält den Player komplett an und erlaubt das Wechseln der reu-Datei, ohne den Player neu laden zu müssen oder springt in den Dateibrowser *
  Z: Einzelbild zurück (nützlich, wenn der Player pausiert ist)
  X: Einzelbild vor (nützlich, wenn der Player pausiert ist) 
  ,: schnelles Zurückspulen
  .: schnelles Vorspulen
  < (Shift + .): langsames Zurückspulen
  > (Shift + ,): langsames Vorspulen
  L: Wiederholung (Loop) des Videos erzwingen (wenn Autoplay deaktiviert ist)
  F1/Shift+F1: Rahmenfarbe ändern **
  +: wechselt zum nächsten Video *
  -: wechselt zum vorherigen Video *
  C=+F: Dateibrowser aktivieren, sofern verfügbar

Joystick in Port 2:
  Links:  Zurückspulen
  Rechts: Vorspulen
  Hoch:   vorheriges Kapitel (nur, wenn das Video Kapitel hat) oder vorheriges Video *
  Runter: nächstes Kapitel (nur, wenn das Video Kapitel hat) oder nächstes Video *
  Feuer:  Pause / Fortsetzen, langes Drücken beim Pausieren: Player stoppen oder in den Dateibrowser springen *
  Links + Feuer:  schnelles Zurückspulen
  Rechts + Feuer: schnelles Vorspulen

*  nur verfügbar, wenn der Dateibrowser aktiviert ist
** häufiges Nutzen dieser Funktion kann Bild und Ton unsynchron machen -> hier hilft ein kurzes Zurückspulen zur Neusynchronisierung

Hinweis: bei Videos mit geringer Framerate reagiert die Steuerung träge, da die Tastatur und der Joystick aus technischen Gründen nur zwischen den Einzelbildern abgefragt wird. Bei solchen Videos muss man die Taste / Joystick gedrückt halten, bis der Player den Befehl ausführt. 

Folgende Steuerungsmöglichkeiten existieren im Dateibrowser:

Tastatur: 
  Cursor links:  zur vorherigen Seite springen (vorherige 20 Einträge)
  Cursor rechts: zur nächsten Seite springen (nächste 20 Einträge)
  Cursor hoch:   Cursor nach oben bewegen
  Cursor runter: Cursor nach unten bewegen
  RETURN: Ins gewählte Verzeichnis wechseln oder gewählte Datei in die REU laden und starten
  <-: eine Verzeichnisebene nach oben wechseln (cd ..)
  F1/F2: Rahmenfarbe ändern
  F3/F4: Hintergrundfarbe ändern
  F5/F6: Farbe für Verzeichniseinträge ändern
  F7/F8: Farbe für Dateieinträge ändern
  INST/DEL: Farbe der Kopf- und Fußzeile und des Cursors ändern
  A: Autoplay an-/ausschalten
  I: Infoscreen an-/ausschalten oder zeitgesteuerten, automatischen Wiedergabestart aktivieren 
  HOME: ins Home-Verzeichnis wechseln, sofern festgelegt und gültig, sonst Wechsel ins Wurzelverzeichnis
  SHIFT+HOME: Home-Verzeichnis festlegen
  B: Rahmenfarbe während der Videowiedergabe ändern ("default" nutzt die Farbe, die in der Videodatei hinterlegt ist)
  H: Hilfe-Seiten aufrufen
  S: Einstellungen (Farben, Autoplay, Infoscreen, Home-Verzeichnis) auf dem Flash-Speicher der 1541 Ultimate II(+)(L) oder des Ultimate 64 speichern
  Q: Dateibrowser deaktivieren (der Player verhält sich dann so wie auf einem Gerät auf dem kein Dateibrowser verfügbar ist)
  U: Ultimate-II DOS-Version anzeigen
  +: Zeit bis beim Anzeigen eines Infoscreens die Wiedergabe automatisch beginnt um 1 Sekunde erhöhen und automatischen Wiedergabebeginn aktivieren
  -: Zeit bis beim Anzeigen eines Infoscreens die Wiedergabe automatisch beginnt um 1 Sekunde verringern und automatischen Wiedergabebeginn aktivieren

Joystick in Port 2:
  Hoch:   Cursor nach oben bewegen  
  Runter: Cursor nach unten bewegen
  Links:  zur vorherigen Seite springen
  Rechts: zur nächsten Seite springen
  Feuer:  ausgewählte Datei laden und abspielen oder ausgewähltes Verzeichnis öffnen

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

Hinweise zur Autoplay-Funktion und Weiterschalten von Videos:
Im Verzeichnis aus dem man Videos automatisch abspielen lassen oder in dem man Videos weiterschalten möchte sollten sich nur Koalavideo-Dateien befinden, da sonst der Player bei Erreichen einer Datei, die kein Video ist, die Wiedergabe mit der Fehlermeldung "NO KOALAVIDEO FILE!" unterbricht.

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

Fehlermeldungen vom Dateibrowser:

NO KOALAVIDEO FILE! 
-> es wurde eine Datei ausgewählt, die kein Video ist, das mit dem Koalavideo-Player abgespielt werden kann
-> der Fehler kann auch auftreten, wenn eine fehlerhafte Firmware genutzt wird (trat bei mir mit der 1541 Ultimate II+ - Firmware 3.10j und 3.10h auf)
VIDEO REQUIRES KOALAVIDEO Vxx!
-> es wurde ein Video ausgewählt das eine neuere Version des Players benötigt - Vxx ist die benötigte Playerversion
ERROR SAVING SETTINGS! 
-> Einstellungen konnten nicht gespeichert werden - Fehler erscheint z.B., wenn der Flashspeicher voll ist
ERROR LOADING SETTINGS!
-> erscheint beim Programmstart, wenn ein Fehler beim Laden der Einstellungen aufgetreten ist, z.B. durch eine beschädigte config-Datei
No config file on flash
-> keine wirkliche Fehlermeldung, sondern ein Hinweis, dass es keine config-Datei auf dem Flashspeicher gibt und die Standardeinstellungen geladen wurden
DIRECTORY EMPTY
-> keine wirkliche Fehlermeldung, sondern ein Hinweis dass das Verzeichnis leer ist und deshalb keine Einträge angezeigt werden können 

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

Grenzen des Dateibrowsers:

Es können maximal 255 Einträge geladen werden. Die maximale Datenmenge die aus einem Verzeichnis eingelesen werden kann ist ungefähr 8,8 KB. Diese Grenze kann erreicht werden, wenn sich viele Einträge mit langen Namen in einem Verzeichnis befinden. Wenn eine dieser Grenzen erreicht wird, wird das Einlesen beendet, wodurch nicht alle Einträge angezeigt werden können. Die bereits eingelesenen Einträge können normal genutzt werden.

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

Das heruntergeladene Archiv enthält folgende Dateien:

- Koalavideo_v06.prg: der eigentliche Videoplayer für den Commodore 64
- liesmich.txt: diese Datei mit Infos zum Programm
- readme.txt: die Englische liesmich-Datei mit Infos zum Programm
- Ultimate 64 Ultimate-II(+)(L) settings.pdf: Darstellung der benötigten/empfohlenen Einstellungen des Ultimate 64 / Ultimate-II(+)(L)-Moduls

Verzeichnis "Source" (Quellcodes und -dateien):
- Unterverzeichnis "Koalavideo v06": Quellcodedateien des eigentlichen Videoplayers fürs C64 Studio: am besten die Datei "Koalavideo_v06.s64" als "Solution or Project" öffnen
- Unterverzeichnis "macOS": Quellcode des Koalavideo v02 REUmaker zur Kompilierung mit der macOS-Version von QB64 (bereitgestellt von SkulleateR aus dem forum64) + Anleitung
- Anleitung Erstellung eines Koalavideos.odt: Deutsche Anleitung zur Erstellung eines Koalavideos (LibreOffice Writer-Format)
- How to make a Koalavideo.odt: Englische Anleitung zur Erstellung eines Koalavideos (LibreOffice Writer-Format) 
- Koalavideo v01-v06 Playlistmaker.bas: der Quellcode des Playlistmakers - kann mit QB64 kompiliert werden
- Koalavideo v06 REUmaker Linux.bas: der Quellcode des REUmakers (Linux-Version) - kann mit QB64 kompiliert werden
- Koalavideo v06 REUmaker Windows.bas: der Quellcode des REUmakers (Windows-Version) - kann mit QB64 kompiliert werden
- Ultimate 64 Ultimate-II(+)(L) settings.odt: Darstellung der benötigten/empfohlenen Einstellungen des Ultimate 64 / Ultimate-II(+)(L)-Moduls (LibreOffice Writer-Format) 

Verzeichnis "Tools" (Hilfsdateien zur Erstellung eines Koalavideos):
- Unterverzeichnis "macOS": Tools und Anleitung zur Erstellung eines Koalavideos unter macOS (bereitgestellt von SkulleateR aus dem forum64, mangels macOS von mir nicht getestet)
- Anleitung Erstellung eines Koalavideos.pdf: Deutsche Anleitung zur Erstellung eines Koalavideos (pdf-Format)
- How to make a Koalavideo.pdf: Englische Anleitung zur Erstellung eines Koalavideos (pdf-Format)
- Koalavideo v01-v06 Infoscreeneditor DE.prg: C64-Programm (Deutsche Version), um nachträglich einen Infoscreen erstellen / ändern zu können, kann im Emulator genutzt werden
- Koalavideo v01-v06 Infoscreeneditor EN.prg: C64-Programm (Englische Version), um nachträglich einen Infoscreen erstellen / ändern zu können, kann im Emulator genutzt werden
- Koalavideo v01-v06 Playlistmaker.exe: Programm zur automatischen Erstellung einer Playlist (s. Anleitung zur Erstellung eines Koalavideos)
- Koalavideo v05-v06 Calculator.ods: Datei für Libre Office Calc zur Berechnung, ob ein Video mit der angegebenen Länge, Framerate und dem Seitenverhältnis in die REU passen wird
- Koalavideo v06 REUmaker Linux: Programm zur Kompilierung von Koalabildern und einer geeigneten wav-Datei zu einer Koalavideo-Datei, die mit dem Koalavideo-Player abspielbar ist (Linux-Version)
- Koalavideo v06 REUmaker Windows.exe: Programm zur Kompilierung von Koalabildern und einer geeigneten wav-Datei zu einer Koalavideo-Datei, die mit dem Koalavideo-Player abspielbar ist (Windows-Version)
- Project One auto-convert.au3: Konvertierungsscript für "AutoIt", das automatisch alle bmp-Dateien in Koalabilder mit dem Programm "Project One" umwandeln kann
- Retropixels batch.bat: Batch-Datei zur Konvertierung der Bilder mit Hilfe des Kommandozeilentools "Retropixels"

Hinweis: Für den Koalavideo v01-v06 Infoscreeneditor wird keinen separater Quellcode bereit gestellt, da es sich um ein BASIC-Programm handelt und man somit den Quellcode durch Eingabe des C64-Befehls LIST aufrufen kann.

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

Versionhistorie:

v01: - erste funktionierende Version, die die Videos einfach nur abspielt und einen Infoscreen anzeigen kann, sofern dieser in der Videodatei enthalten ist

v02: - Playersteuerung hinzugefügt: Vorspulen, Zurückspulen, Pause, Einzelbildschritte und Stop (erlaubt das Wechseln der reu-Datei ohne den Player neu laden zu müssen)
     - Kapitelsprünge (nur verfügbar, wenn in der Videodatei Kapitel festgelegt wurden)
     - REUmaker erweitert: erlaubt nun das Einfügen von Kapiteln und speichert die Eingaben zum Infoscreen und die Kapitelsprünge in einer Datei, um sie bei
       Neuzusammenstellung eines Videos erneut nutzen zu können, ohne alles neu eingeben zu müssen
     - Anleitung zur Erstellung eines Koalavideos erweitert um eine schnellere Konvertiermöglichkeit mittels des Kommandozeilenkoverters "Retropixels" und einer Batch-Datei

v03: - Bugfix: bei Dateien, bei denen der Ton mehr als 50% der REU belegt, gab es Tonfehler beim Spulen und bei Kapitelsprüngen (gemeldet vom Youtuber Yucel Bilik)
     - Bugfix: Player stürzte manchmal ab, wenn man direkt nach dem Spulen auf Pause gedrückt hat
     - Bugfix: Videos mit einem Wert für die Abspielgeschwindigkeit von mehr als 127 (Slideshows) wurden zu schnell abgespielt
     - Videos mit geringer Framerate starten nun schneller (es wird nicht mehr unnötig lange auf das erste Bild gewartet), vermeidet auch Bild-/Ton-Asynchronität
     - weitere kleine Anpassungen, um Fehler bei bestimmten Videoparametern zu vermeiden
     - verschiedene Fehler in den Tools REUmaker, Playlistmaker und Infoscreeneditor behoben
     - Tools zur Erstellung eines Koalavideos unter macOS hinzugefügt (bereitgestellt von SkulleateR aus dem forum64, mangels macOS nicht getestet)

v04: - eingebauter Dateibrowser mit dem man direkt im Programm Videos für die Wiedergabe auswählen kann (benötigt ein 1541 Ultimate-II(+)(L)-Modul oder einen Ultimate 64)
     - Autoplay-Funktion: spielt alle Videos in einem Verzeichnis nacheinander ab (benötigt ein 1541 Ultimate-II(+)(L)-Modul oder einen Ultimate 64)
     - während der Videowiedergabe kann zum vorherigen oder nächsten Video gesprungen werden (wenn der Dateibrowser aktiviert ist)
     - im Dateibrowser können die Infoscreens abgeschaltet oder ein zeitgesteuerter, automatischer Wiedergabebeginn eingestellt werden
       (nützlich bei Nutzung der Autoplay-Funktion)
     - Einstellungen im Dateibrowser können auf dem Flash der unterstützten Geräte gespeichert werden
       (diese werden beim nächsten Programmstart automatisch geladen und angewendet)
     - die Rahmenfarbe kann während der Videowiedergabe geändert werden (nur temporär für das aktuell laufende Video)
     - mit der Taste L kann das aktuell abgespielte Video auf Dauerwiedergabe (Loop) gezwungen werden (unwirksam, wenn Autoplay aktiv ist)
     - das Farb-RAM wird beim Start des Players initialisiert -> vermeidet falsche Textfarben, wenn der Player gestartet wird,
       nachdem andersfarbiger Text auf dem Bildschirm geschrieben wurde
     - der Dateibrowser kann vor dem Programmstart mit dem BASIC-Befehl POKE 2063,1 oder den Assemblerbefehlen lda #1 und sta $080F deaktiviert werden
       (nützlich, wenn der Player aus einer anderen Anwendung, die bereits ein Video in die REU geladen hat, gestartet werden soll, z.B. vom WiC64 aus) 
     - die Infoscreens und Fehlermeldebildschirme können mit dem Feuerknopf des Joysticks verlassen werden
     - Bugfix: es gab Tonfehler beim Spulen, wenn die REU komplett mit Video- und Audiodaten gefüllt war 

v05: - 2.35:1 / 21:9 (cinemascope) Videoformat hinzugefügt das Framerates von bis zu 25 fps ermöglicht
     - Bugfix: im Dateibrowser konnte beim ersten Starten des Players Grafikmüll erscheinen wenn nach keine config-Datei auf dem Flashspeicher des Ultimate-II(+)(L)-Moduls 
       abgespeichert war
     - Bugfix: 16:9-Videos mit Dauerschleife-Kapiteln wurden nicht korrekt abgespielt (gemeldet vom Youtuber Yucel Bilik)
     - Bugfix: eine diagonale Joystickbewegung im Dateibrowser startete den Player ohne eine Datei zu laden
     - REUmaker: Unterstützung für wav-Dateien im wavex-Format hinzugefügt
     - REUmaker: zeigt nun eine Fehlermeldung, wenn die Playlist Bildnummern enthält, die höher sind als die Anzahl der gefundenen Koalabilder - 1 (da die Bildnummern bei 0 beginnen)

v06: - Ultimate Audio Unterstützung hinzugefügt: dies erlaubt eine gute Tonwiedergabe auf Ultimate 64-Boards oder Commodore 64 Ultimate-Geräten, die keinen echten SID oder guten 
       Nachbau verbaut haben
     - Hilfeseiten in den Dateibrowser eingebaut, die in Kurzform die Steuerung erklärt
     - Einstellung für die Rahmenfarbe während der Videowiedergabe hinzugefügt ("default" nutzt wie bisher die in der Videodatei hinterlegte Farbe)
     - REU-Maker: Störgeräusche am Ende eines Videos bei der Nutzung bestimmter wav-Dateien behoben
     - REU-Maker: Linuxversion hinzugefügt
 