KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #developer-tools #dsh-plugin #ai-agent #mcp #deepseek-harness

desidulate

★ 19 Open GitHub ↗

Tools for analyzing C64 SID music

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# desidulate

## Overview

desidulate is a suite of command line "decompiler" tools for transcribing and analyzing [C64/SID](https://en.wikipedia.org/wiki/MOS_Technology_6581) music, based on [Pandas](https://github.com/pandas-dev/).

desidulate works directly on SID register log files (those generated by [VICE's](https://vice-emu.sourceforge.io/) `-sounddev dump` option), which means it can parse music from any C64 software that VICE can run (game, demo, .sid file, etc).

desidulate is intended to help SID composers and musicologists understand the SID and SID instrument design process more quickly and completely, find unexplored territory, and build upon the SID music legacy. desidulate was also written to assist [CHIME RED](https://github.com/anarkiwi/chime_red2) Tesla coil synthesizer research, and to provide training data for [Magenta](https://magenta.tensorflow.org/).

## Installing

To install the most recent release:

```
$ pip install desidulate
```

To install a development release:

```
$ git clone https://github.com/anarkiwi/desidulate
$ pip install desidulate/
```

## Usage overview

desidulate is intended to be used as a pipeline, where the input is a VICE emulator SID register dump, and the output could be WAVs, Simple MIDI Files (SMF), Pandas dataframes representing SID "instruments", or even entire performances for analysis.

### Transcribing to SSFs

The first task in the desidulate workflow, is to transcribe a VICE register log file, into desidulate SSFs (SID Sound Fragment) dataframes. A single SSF, represents all SID register changes made a SID voice (and its modulating voice frequency/test status, if ring or synchornization is used), in between the time the voice's GATE bit is changed from 0 to 1 (which starts the envelope generator).

desidulate reads the register log file and produces a dataframe with all SSFs, and another dataframe with a time based log, of when each SSF was triggered. An SSF may be triggered many times during a performance. desidulate eliminates redundant register writes (for example, where the same values are repeatedly written to the same registers).

#### Generating a register logfile

In following examples, we are using VICE's _vsid_ player (we could also use _x64sc_) to work with _Cauldron_II_Remix.sid_ from the [High Voltage SID Collection](https://www.hvsc.c64.org/).

```
$ vsid -sounddev dump -soundarg C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.sid.dump -warp -limit 300000000 C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.sid
```

#### Generating SSFs

```
$ reg2ssf C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.sid.dump
```

_reg2ssf_ identifies all SSFs (see above) and writes them to `C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.ssf.zst`, and log file `C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.log.zst`.

SSFs are output in order of frequency of occurence, most first:

```
$ zstdcat C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.ssf.zst |head
hashid,clock,pr_frame,gate1,freq1,pwduty1,pulse1,noise1,tri1,saw1,test1,sync1,ring1,freq3,test3,flt1,fltcoff,fltres,fltlo,fltband,flthi,fltext,atk1,dec1,sus1,rel1,vol,rate,pr_speed,hashid_noclock,count
-2174233589037180891,0,0,1,,,,,,,1,,,,,,,,,,,,0,2,10,0,15,19339,1,-6871201304917122305,286
-2174233589037180891,19689,1,1,53414,,0,1,0,0,0,,,,,0,,,,,,,,,,,15,19339,1,-6871201304917122305,286
-2174233589037180891,39399,2,1,5614,,0,1,0,0,0,,,,,0,,,,,,,,,,,15,19339,1,-6871201304917122305,286
-2174233589037180891,39421,2,0,5614,,0,0,1,0,0,,,,,0,,,,,,,,,,,15,19339,1,-6871201304917122305,286
-2174233589037180891,58738,3,0,2650,,0,0,1,0,0,,,,,0,,,,,,,,,,,15,19339,1,-6871201304917122305,286
-2174233589037180891,78605,4,0,2650,,0,0,1,0,0,,,,,0,,,,,,,,,,,15,19339,1,-6871201304917122305,286
-5281139747119741370,0,0,1,,,,,,,1,,,,,,,,,,,,0,2,14,0,15,19383,1,757979854999595997,193
```

### Transcribing to SMF

```
$ ssf2midi C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.log.zst
```

_ssf2midi_ generates a SMF file `C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.mid` from _reg2ssf_ log and ssf files (note only the path to the log file is specified).

desidulate will generate a multitrack SMF (one track for each voice, and an additional track for each voice for percussion). The intent is not perfect MIDI reproduction (not possible due to missing features in MIDI like standardized support for filter sweeps, and envelope durations etc) but to allow analysis of SID programming techniques (e.g. how a particular kick sound is made), and to allow a composer to have MIDI based devices accompany a C64 composition without complex hardware integration. Percussion detection is based on the use of the noise waveform, SSF duration, and initial pitch drop detection (SSFs that use noise exclusively, are assigned "hi hat" type sounds, and those SSFs that combine noise with other waveforms are variously assigned kick, snare or tom drums based on frequency). Velocity assignment is done by approximating the mean level of the envelope generator over the entire duration of the SSF.

### Transcribing to WAV

```
$ ssf2wav C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.log.zst --hashid -5281139747119741370 --play
		     hashid  pr_frame  gate1  freq1  pwduty1  pulse1  noise1  tri1  saw1  test1  sync1  ring1  freq3  test3  flt1  fltcoff  fltres  fltlo  fltband  flthi  fltext  atk1  dec1  sus1  rel1  vol   rate  pr_speed      hashid_noclock  count    real_freq  closest_note
clock
0      -5281139747119741370         0      1   <NA>     <NA>    <NA>    <NA>  <NA>  <NA>      1   <NA>   <NA>   <NA>   <NA>  <NA>     <NA>    <NA>   <NA>     <NA>   <NA>    <NA>     0     2    14     0   15  19383         1  757979854999595997    193         <NA>          <NA>
19694  -5281139747119741370         1      1  50416     <NA>       0       1     0     0      0   <NA>   <NA>   <NA>   <NA>     1      768      15      1        1      0       0     0     2    14     0   15  19383         1  757979854999595997    193  2960.697601           102
39063  -5281139747119741370         2      0   3537     2048       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       40      15      0        0      1       0     0     2    14     0   15  19383         1  757979854999595997    193   207.711588            56
58720  -5281139747119741370         3      0   2974     2048       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       16      15      0        1      1       0     0     2    14     0   15  19383         1  757979854999595997    193   174.649212            53
78378  -5281139747119741370         4      0   2974     2048       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1      128      15      0        0      1       0     0     2    14     0   15  19383         1  757979854999595997    193   174.649212            53
Playing WAVE 'C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.wav' : Signed 16 bit Little Endian, Rate 11025 Hz, Mono
{'drum_instrument': 45, 'samples': 657, 'loudestf': 167, 'last_clock': 78378, 'initial_pitch_drop': 4}
```

Where `--hashid` is the SSF to play. If not specified, all WAVs for all SSFs will be generated.

### Transcribing to Sid Wizard instrument

desidulate can, with some limitations, transcribe an SSF to a Sid Wizard instrument. desidulate attempts to optimize the transcribed instrument by detecting and automating filter and PWM curves.

1. Generate WAVs for every SSF in a song:

```
$ ssf2wav C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.ssf.zst
```

2. Listen to the WAVs, to find the instrument you wish to transcribe, which will be indentified with a hashid in the filename.

3. Transcribe the SSF into an instrument (in this case, a kick sound):

```
$ ssf2swi C64Music/MUSICIANS/L/Linus/Cauldron_II_Remix.ssf.zst -1975247557004053752
multispeed: 1
ADSR: 05F0

F WFARP PULSE  FILT
0   00  81BB  ....  BF60
1   01  41A7  88..  BF03
2   02  419B  84..  02F8
3   03  ....  0340  BF12
4   04  ....  85..  BF06
5   05  ....  0340  BF02
6   06  ....  86..  BF03
7   07  ....  0240  ....
8   08  ....  ....  ....
9   09  ....  ....  ....
10  0A  ....  ....  ....
11  0B  ....  ....  ....
12  0C  ....  ....  ....

gate1  freq1  pwduty1  pulse1  noise1  tri1  saw1  test1  sync1  ring1  freq3  test3  flt1  fltcoff  fltres  fltlo  fltband  flthi  real_freq  closest_note
0       1   7940     <NA>       0       1     0     0      0   <NA>   <NA>   <NA>   <NA>     1      768      15      1        1      0     466.28            70
1       1   2501     2048       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       24      15      1        1      0     146.87            50
2       1   1250     1024       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       16      15      1        1      0      73.41            38
3       1   1250     1088       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1        8      15      1        1      0      73.41            38
4       1   1250     1152       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1      144      15      1        1      0      73.41            38
5       1   1250     1216       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       48      15      1        1      0      73.41            38
6       1   1250     1280       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       16      15      1        1      0      73.41            38
7       1   1250     1344       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       24      15      1        1      0      73.41            38
8       1   1252     1408       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       24      15      1        1      0      73.52            38
9       1   1254     1472       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       24      15      1        1      0      73.64            38
10      1   1256     1536       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       24      15      1        1      0      73.76            38
11      1   1254     1600       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       24      15      1        1      0      73.64            38
12      1   1252     1664       1       0     0     0      0   <NA>   <NA>   <NA>   <NA>     1       24      15      1        1      0      73.52            38

```

4. enter the values into SID Wizard (a direct SWI exporter is planned), and play the sound with "z!"

![Alt text](https://raw.githubusercontent.com/anarkiwi/desidulate/main/docs/swishot.png)

## Ongoing work

* Pitchbending for following small pitch changes ([Magenta](https://github.com/magenta/magenta/issues/1902) does not use pitchbends as of March 2021)
* Use of MIDI aftertouch for velocity dynamics.
* VICE multi SID support (the dump driver currently supports only one SID).
* Export to [defMON](https://www.vandervecken.com/defmon).

## References

* https://github.com/c64cryptoboy/ChiptuneSAK
* https://github.com/M3wP/XSID
* https://haendel.ddns.net/~ken/
* https://csdb.dk/release/?id=152422

desidulate

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README