SONGLENGTH DATABASE =================== Since HVSC#68 there are several ways to read the song lengths info of a SID, via: - Song length database (new format) - Song length database (old format) - SSL files for players that run on C64 hardware Since HVSC#71 only the new format of the song length database is included in HVSC. The new format has MD5 hashes based on the full content and is easy to implement for SID Players and tooling. The old format has MD5 hashes with a specific MD5 calculation. If you need the old format for tooling/players that don't support the new format then you can generate the file with a conversion script. See section 'THE OLD FORMAT' for details on how to generate the file. SSL files are needed when you want song length info for sidplayers that run on a C64. A script can be used which extracts the song length info and generates SSL files. See "SSL FILE FORMAT" section for more info. The song length for each SID and sub tune can be found in: C64Music\DOCUMENTS\Songlengths.md5 Each SID has a unique MD5 hash that SID players can use to get the song lengths of a SID. For every HVSC release a new Songlengths database is provided with updated and added hashes. Therefore, always ensure with each HVSC update that the latest Songlengths database is used. The song length of a SID is based on the PAL / NTSC emulation that the SID is made for. If you decide to play the SID on a different frequency than intended then the song length will not be correct. THE NEW FORMAT ============== The new format of the song length is used in file: C64Music\DOCUMENTS\Songlengths.md5 The file format is INI-style. The first line of the file is always: [Database] Commented lines start with a semi colon. Hashes are MD5 fingerprints (a 32-character string in HEX) and can be calculated based on the full content of the SID file (including the SID header). An example of a song length line: c4c5ff8cfefdf683c50e66775cfac1ee=3:57 1:02 0:06 0:02 0:01 0:01 0:02 0:04 0:03 0:02 0:03 The line has the format: key=value Where key is the MD5 hash and the value includes the song lengths which are separated with a space. Each song length is of format: mm:ss[.SSS] where mm, ss and SSS are numbers and mm never has a leading zero. The .SSS is the number of milliseconds and this value is optional. The square brackets indicate that it is optional, they are not part of the real value. The number of digits of the value of SSS is minimal 1 and maximal 3. The ss.SSS value can be seen as the floating-point number of the number of seconds. The minimum song length of a SID tune is 1 second when milliseconds are not provided. Examples of song length values: 1:02 1:02.5 1:02.500 The last two examples indicate that the song length is 1 minute and 2.5 seconds. Above every song length line, a comment is placed which includes the file path of the SID within HVSC. THE OLD FORMAT ============== Most SID players support the old format. Since HVSC#71 only the new format of the song lengths database is included in HVSC. Please make sure to update your favourite SID player or generate the file with the song lengths in the old format for each HVSC update. To make sure that you can always use old SID players and tools, we provide a script so you can generate the old song lengths file in the old format for the latest HVSC release. For each HVSC update you need to generate the file again. You can use the following script to generate the Songlengths.txt file: https://hvsc.de/download/files/tools/ConvertMd5ToSldbTxt.zip To generate the file, call the script like this: python ConvertMd5ToSldbTxt.py This will generate the file Songlengths.txt in the current folder where you execute the script. Once it is generated, please copy the file to the DOCUMENTS folder in HVSC: \DOCUMENTS\ After this, old tooling/players can read the song lengths again. The old format has the same file structure as the new format, but differs in: - MD5 hash based on different reading of the content of the file - no milliseconds support, format of song length is mm:ss - optional attributes (G, M, Z, B) after the song length The meaning of the attributes: (G) = all three SID voices have had GATE off (M) = master volume turned zero (Z) = all three SID voices have been silent (B) = sidtune does bad things in memory / timestamp estimated An example: a08c08aa1c74990c7d753e8c1d2f023e=3:57 1:02 0:06(G) 0:02(G) 0:01(G) 0:01(G) 0:02(G) 0:04(G) 0:03(G) 0:02(G) 0:03(G) The calculation of the MD5 fingerprint is as follows: - Read all data starting from the data offset - Read init address (lo-byte first) - Read play address (lo-byte first) - Read number of songs (lo-byte first) - For each speed flag bit, calculate if the speed is CIA or VBI speed. Then perform the following for all 32 bits: - read 0 for VBI speed - read 60 for CIA speed - When the SID is NTSC specific, read 2 You can find a little Python script with test cases here: https://hvsc.de/download/files/tools/sid2md5_script_plus_test_cases.zip SSL FILE FORMAT =============== SSL stands for SID Song Length. Since on a C64 the song lengths database is too big, we have defined a new file format so that players can read the song length info in an easy way on specific hardware where all HVSC files can be stored. You can use the following script to generate the files and folders: https://hvsc.de/download/files/tools/Generate_SSL_Files.zip This script will generate SSL files for each SID. The SSL files will be put in the SONGLENGTHS folders. To generate the files and folders, call the script like this: python Generate_SSL_Files.py To remove the files and folders, call the script like this: python Generate_SSL_Files.py -d Note that for every HVSC update, the SSL files and SONGLENGTHS folders need to be thrown away using the -d option of the tool before updating HVSC. After the update the script can be run again to create the folders with the SSL files. File format and HVSC structure: - Each folder in HVSC that includes one or more SID files will get another folder called SONGLENGTHS (in uppercase). - The SONGLENGTHS folder gets all the filenames of the parent folder but instead of the "sid" extension it will get the extension "ssl". - SSL files are binary files where the song length of each sub tune is defined in BCD format (2 bytes per sub tune), minutes first then seconds. Milliseconds are not supported. - Maximum sub tunes in a SID is 256 and therefore the maximum length of the SSL file is 512 bytes. - The SONGLENGTHS folders may be hidden on the file system (up to the user to decide). An example: We have the following in Songlengths.md5 defined: ; /MUSICIANS/H/Hubbard_Rob/Commando.sid c4c5ff8cfefdf683c50e66775cfac1ee=3:57 1:02 0:06 0:02 0:01 0:01 0:02 0:04 0:03 0:02 0:03 The Commando.ssl file will look like this in HEX: 03 57 01 02 00 06 00 02 00 01 00 01 00 02 00 04 00 03 00 02 00 03 The file structure will look like this for files Chimera and Commando: SONGLENGTHS Chimera.ssl Commando.ssl Chimera.sid Commando.sid When a sidplayer reads e.g. Commando.sid, it should check if the SONGLENGTHS folder exists and then read the Commando.ssl file to read the song length info. If you don't want to see the SONGLENGTHS folders in your SID player, then you can make the folders hidden on your device. The SID player can still read the folders but it will not show it. See the Generate_SSL_Files.zip readme file for info of how to make the folders hidden, depending on your operating system.