                     HVTC-ted converter by Hermit

A tool to create HVTC-ted music collection from original HVTC folder and webpage
html-information. (TED-format is an enhancement of TMF format with the
possibility to have the header/metadata at the end of the file.)

Prior Art: Thanks to Luca for collecting and processing all these TED music
           PRG files over the years into the original HVTC, and thanks to Siz
           for the new TMF-format specification that includes subtune-playtimes
           (durations), see tedmusiccollection.html.

Prerequisites:
'player' folder extracted from hvtc zip-archive into the same folder as HVTCted
'player-new' folder contains saved tunes that aren't yet in the hvtc zip file
             (just downloadable one-by-one from the plus4world/hvtc page)
'html' folder containing saved .html files (one-by-one from plus4world/hvtc)
        containing the individual TED-tunes. The html files are not included
        in this archive as they adds up to 15MB. But the resulting 'info'
        folder is contained (up to info from 877.html), so you won't need them.

Usage:
-If 'html' is given as argument, it will process the 'html' folder content into
 formatted .txt files 'html/info' folders.
-If a foldername is used as argument, it will generate the target folders with
 .ted files (described below).
 If an individual tune-name (without path but having '.prg' extension) is given
 as 2nd argument, only that file will be found in the given folder, and gets
 converted to TED file.


Generated folders:

'html/info' contains available metadata-info in .txt files converted from
            'html' folder files by 'HVTCted html' command.

'edits/missing-info' contains missing metadata-info not extracted from the html
                     files and not found and filled in 'edit' folder's txt files
                     either. If the Author-name or tune-title is missing for
                     some reason, HVTCted takes this info from the foldername
                     and filename.

'edits' can have the .txt files for manual edits/completions of the missing or
        incorrect metadata, format: 'FieldName: Value' (SPACE is essential).
        Processed together with 'info' folder but with priority over it, files
        from 'missing-field' folder can be used as a base for editing.
        Field-names: "Title", "Author", "Tool", "Date", "Covers", "Notes",
                     "Channels", "FrameSpeed", "PlayTime", "Looping",
         for subtunes: "Title1","Title2",..., "PlayTime2", "PlayTime3",...,
                       "Covers2",..., "Notes2",...
                       "Looping2",..., "FrameSpeed2",... "Channels2",...
                       "KeyDelay", "KeyPress1","KeyPress2",...
                       (keys are 0..9,A..Z,F1,F2,F3,HELP,Esc,... see in source)
                       "InitAddress", "PlayAddress"  (followed by 4-digit hexa
                       addresses, to convert to subtune-selectable PlayTEDs
                       instead of RealTEDs)

  If a .prg file with the same name and subfolder is present in 'edits' folder,
  it will replace the original .prg file before conversion to TED format.

'HVTC-ted' holds the generated TED files, the essential TED music collection,
           created by 'HVTCted player' then 'HVTCted player-new' commands.

'HVTC-info' folder contains the extra information not contained in the generated
            .TED files (that doesn't have a field or wouldn't fit)


TED-fileformat Info:
I kept the new expanded TMF format specification by Siz as intact as possible,
but these are some compatible additions:

-the BASIC line-number in the SYS starter command is the address of the header
 in the Plus4 memory (starting with "TEDMUSIC" signature)
 If the line-number is less than 4096 and the "TEDMUSIC" signature is found at
 file-offset 17 cRSID assumes the TMF format, otherwise it expects TED-format

-if the PlayAddress field is $0000 in the TED(TMF) header cRSID assumes
 RealTED-mode, which means executing from InitAddress without return
 (In RealTED mode a more complete machine emulation is needed with
  raster-timer-IRQ, KERNAL-ROM routines, etc.)

-if the InitAddress field is $0000 cRSID assumes BASIC SYS starter mode as a
 fallback (with RealTED-mode of course)

-if there's 0 in a 'duration'/'playtime' field for any subtune it should be
 played infinitely (instead of being skipped immediately)

-Character codes in info-fields are not PETSCII but ASCII plus latin
 codepage 8859-1 (or 8859-2?) for accented/extra characters

-FileFlags at offset $27 has a new bit (bit1) to tell if keypress-block is
 present. If it is, it comes right after duration-block,
 starting with a keypress-delay value (in 100ms units) to wait tune-startup.
 Then every subtune has a 1-byte key-value that tells which key
 should be pressed. The number of the key is its position in the FD30/FF08
 matrix, if no info about the key to press, value $FF is there.

-What about default subtune field?

-If I forgot any detail you may take the cRTED player's source code as a basis.


                                           Hermit (Mihaly Horvath) - March 2023
                             (contact by PM at plus4world.powweb.com or csdb.dk)
