An offline Commodore 64 SID analysis tool with a browser UI and command-line interface. It loads PSID/RSID files, executes supported player code with a compact 6510/C64 runtime, records SID register and voice state frame-by-frame, exports the capture as JSON, and can turn a compatible JSON capture into Standard MIDI File type 1.
Release: v1.0.0 · License: GPL-3.0-or-later · Copyright: © 2026 Ulf Bertilsson
The browser workflow runs locally. It does not upload SID or JSON files, and it does not require an API key or network connection after dependencies are installed.
- PSID and RSID header parsing with strict size, song-range, load-address and C64-memory-boundary validation.
- PAL/NTSC timing selection from SID v2NG clock flags.
- In-browser 6502, CIA, VIC-II and SID state simulation for player execution.
- Frame JSON containing all 25 SID registers, voice pitch/envelope/waveform state, gate triggers, and filter state.
- JSON-to-MIDI type-1 export with conductor, voice and optional drum tracks.
- Pitch bend, ADSR/pulse/filter automation, noise-to-drum mapping, optional quantization, gap merging and arpeggio-to-chord conversion.
- Defensive JSON validation at every conversion boundary: frame ordering, register ranges, voice/filter values and capture duration must be internally consistent.
- Smart quantization evaluates straight and triplet grids, while preserving unquantized timing when there is no confident match.
- Fully bundled React/Vite/Tailwind build: no CDN, import map or API key is required at runtime.
- SID files: PSID and RSID versions 1–4 with a valid header, load address, subtune range, and C64-memory-sized program image.
- JSON files: captures produced by this converter, or compatible traces that satisfy the documented frame, register, voice, filter, and timing validation rules.
- MIDI output: Standard MIDI File type 1, suitable for DAWs and sequencers that accept
.midfiles.
The project intentionally does not claim support for multi-SID tunes, ROM-dependent loaders, digi/sample playback, or cycle-perfect raster behavior. See Accuracy boundaries before relying on a conversion for archival or emulation research.
Requirements: Node.js 20+ and pnpm 10+.
pnpm install
pnpm run typecheck
pnpm run build
pnpm run verify
pnpm run devThe browser build is entirely local: SID/JSON data is not uploaded and no API key is required. pnpm run build produces the browser bundle in dist/ and the standalone CLI bundle in dist-cli/; both directories are generated and intentionally excluded from Git.
To use the CLI without the browser after building it:
node dist-cli/sid-json.mjs --help- Open the local URL printed by Vite.
- Drop a PSID or RSID file into SID → JSON.
- Set a capture limit (start with 60 seconds) and select the subtune, numbered from 1.
- Choose Convert to JSON. A successful capture also prepares a MIDI download using the selected MIDI settings.
- Download JSON for forensic/register analysis, or MIDI for a DAW sketch.
For a JSON capture produced elsewhere, use the JSON → MIDI panel. The browser validates the file before conversion and reports incompatible captures instead of producing a broken MIDI file.
| Goal | Recommended command or setting |
|---|---|
| Inspect header and supported subtunes | sid-json inspect tune.sid |
| Preserve exact frame positions | sid-json sid-to-json tune.sid --seconds 180 |
| Create a musical first-pass MIDI | sid-json sid-to-midi tune.sid --quantize auto --note-duration smart |
| Keep chip arpeggios as separate notes | Do not use --arps-to-chords |
| Turn fast arpeggios into DAW chords | Add --arps-to-chords |
| Treat noise as pitched material | Add --no-drums |
The same parser, capture runtime and MIDI writer are available without the browser UI. Build once, then run the CLI:
pnpm run build:cli
pnpm run cli -- inspect tune.sid
pnpm run cli -- sid-to-json tune.sid --seconds 180 --song 1 -o tune.json
pnpm run cli -- json-to-midi tune.json --quantize none -o tune.mid
pnpm run cli -- sid-to-midi tune.sid --json-out tune.json --quantize auto -o tune.midsid-to-json defaults to a 60-second capture and writes JSON alongside the source SID. sid-to-midi performs capture and MIDI export in one command, with optional --json-out. json-to-midi accepts --quantize (including 1/16T and 1/8T triplets), --octave-shift, --min-note-frames, --note-duration, --no-expression, --minimal-automation, --no-merge-gaps, --no-drums, and --arps-to-chords. Use validate-json before batch MIDI conversion. Run pnpm run cli -- --help for the complete reference.
pnpm run verify creates an isolated synthetic PSID fixture and checks malformed SID/JSON rejection, deterministic SID-to-JSON output, PAL frame timing, custom-IRQ PSID dispatch, and the complete MIDI chunk/end-marker structure.
See the detailed usage guide for copy-ready commands, output conventions, option recipes, and troubleshooting.
- JSON is the durable analysis format. It includes parsed SID metadata and primary register/voice/filter snapshots at video-frame boundaries.
- MIDI is a type-1 Standard MIDI File designed for import into mainstream DAWs. It conveys inferred notes and controller automation, not SID audio.
- Validation is built into the browser and available through
sid-json validate-json; use it before converting archived or third-party traces.
Generated files are never committed by default. Keep captures under a local exports/ directory or another project-specific location.
The current public release is v1.0.0. It is validated with TypeScript type checks, deterministic synthetic PSID/RSID captures, JSON validation, MIDI chunk checks, and a production Vite build. Report reproducible issues through the issue tracker, including the SID header from sid-json inspect and the exact command or browser setting used.
The MIDI export represents musical control data inferred from SID registers, not rendered SID audio. It maps frequency to notes/pitch bend, gate/envelope to note timing and velocity, pulse and filter values to controller data, and SID noise to General MIDI drum notes. Use the JSON export when you need the raw register capture for inspection or a different downstream mapping.
For the timing model, supported C64 runtime behavior, JSON fields, MIDI controller map, and practical export recipes, see the emulation and format guide.
The included runtime is a pragmatic SID-player tracer, not a transistor-level 6581/8580 audio emulator. It supports RAM banking, a minimal vector/IRQ boot environment, CIA timer IRQs, VIC raster IRQs and standard IRQ indirection for conventional player drivers. Complex loaders, ROM-dependent RSID programs, multi-SID files and cycle-perfect raster effects may require a full C64 emulator. Unsupported 6502 opcodes, non-returning init routines and over-budget PSID play calls fail explicitly rather than silently producing a partial capture.
App.tsx browser workflow and export controls
services/sid/SidParser.ts PSID/RSID validation and metadata parsing
services/sid/SidPlayer.ts C64 execution and frame capture
services/sid/C64System.ts CPU bus, CIA and VIC timing model
services/sid/SidChip.ts SID register/envelope snapshot model
services/sid/JsonToMidi.ts JSON-to-Standard-MIDI writer
services/sid/SidTypes.ts stable JSON capture types
docs/USAGE.md CLI recipes and troubleshooting
docs/EMULATION_AND_FORMAT.md runtime, JSON and MIDI reference
Before submitting a change, run:
pnpm run typecheck
pnpm run verify
pnpm run buildThe regression suite uses temporary synthetic PSID and RSID fixtures. It checks deterministic captures, PAL timing, PSID direct-play dispatch, CIA IRQ-driven RSID execution, malformed SID/JSON rejection, and generated MIDI chunk structure.
Copyright (C) 2026 Ulf Bertilsson.
This project is licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). See LICENSE and COPYRIGHT.
The repository includes the complete, unmodified GNU GPL version 3 text. The -or-later designation permits recipients to follow GPLv3 or any later version published by the Free Software Foundation.