JSIDPlay2 User Guide

JSIDPlay2 provides three software emulation choices. ReSID is based on Dag Lem’s work. ReSID-fp includes Antti S. Lankila’s combined-waveform and distortion emulation and remains the default. The optional ReSIDfp Circuit (RESIDFP_CIRCUIT) shares our ReSIDfp digital core and uses newer 6581 and 8580 analogue filter, mixer and volume models from libresidfp.

In the browser, choose Configuration / Emulation / Default Emulation. On the desktop, use the emulation selector in the toolbar or Settings / Emulation Settings…​. Per-SID overrides can force a different emulation or MOS6581/MOS8580 model; leave them at Default/Automatic to follow the tune and default settings.

Choose the desktop sound device in the toolbar and configure its slots or network address there. For browser hardware playback, open Configuration / USB, enable USB, start playback, and select the attached device when prompted. This needs a browser with WebUSB support and permission to access the device. Follow that panel’s operating-system setup instructions, and connect the hardware’s audio output to your speakers or audio interface. Voice and sample mute controls also work with ExSID, HardSID, and USBSID-Pico; device buffering can delay when a change is heard.

Developers implementing their own device can use the Network SID Device protocol.

Install OpenJDK 21 or newer and extract the archive matching your operating system and CPU architecture. Desktop packages are available for Windows x64, Linux x64/AArch64, and macOS x64/AArch64 (Apple Silicon). Use the supplied launcher so the included JavaFX libraries and native libraries are found.

Note: Whereas Windows users get an executable (.EXE) to launch:

On Linux, launch from the extracted directory:

On macOS, use jsidplay2.command or jsidplay2-console.command in the extracted directory. The .sh launchers can also be run from a terminal in that directory.

To play a file immediately, pass its path to the console launcher, for example:

JSIDPlay2 can also be run using Docker. To start JSIDPlay2 using Docker, you can use the provided docker-compose.yml`s in `src/main/docker:

Run this from a source checkout after configuring the host’s display and audio access. This starts the desktop UI service; the same Compose file also contains a console service. Network SID Device and server deployments use their own Compose files in src/main/docker.

The backend loads assembly64-credentials.properties from user.dir first, then user.home, merging both files with home-directory values overriding duplicate keys, like directoryServlet.properties. An explicit -Djsidplay2.assembly64.credentials selects a single file instead. The server Compose file mounts /home/ken/assembly64-credentials.properties from the Docker host read-only at /root/assembly64-credentials.properties, matching the backend’s default location in the container user’s home directory. Keep the host file private with mode 600 and recreate the server container after adding the mount. Credentials are usable only by web administrators and stay outside the image.

If the browser blocks sound, click a playback control to allow audio. Your volume, emulation settings, and other preferences are saved in that browser’s site storage. See Sharing and downloads to share hosted or uploaded local content with its companions.

Open Screen for video and the virtual keyboard. Configure a gamepad and joystick port under Configuration / Joystick. On touch devices, enable Virtual joystick (touch) there and use the V-Joystick button on the screen view to enter fullscreen controls. Choose Configuration / Audio / Latency / Gaming, then restart the game to reduce input lag. Standard mode uses larger buffers for more stable music playback.

The web player pairs CGSC .mus/.str and _a.mus/_b.mus files automatically in server collections and Assembly64 releases. For local files, select both parts together in File / Load content or the playlist picker. A pair appears as one playlist item. To add the second part after loading the first, use File / Add companion… and select the matching file. The browser can only use local files you select; it cannot search their directory for a sibling. .dat files keep their existing PSID handling.

A demo can also have a required .crt cartridge or .reu memory image as a companion. Select one demo and one cartridge/REU image together, or load the demo and attach its image through File / Add companion…. The cartridge or REU image is installed before the demo starts. Cartridge requirements are explicit; unrelated cartridges in the same directory are not attached automatically. A CRT can explicitly be combined with a REU; other expansion choices remain exclusive. Cartridges may conflict with the REU’s I/O addresses, so compatibility depends on the software.

For StarTreu, select a 512 KiB REU and enable StarTreu timing workaround in the web cartridge configuration. Enable it before loading the CRT, or reset afterwards. This optional compatibility setting selects the timing version already included in the recognised cartridge and enables the VICE bus handoff needed by its following portrait effect. It is off by default and leaves the original file and other cartridges unchanged. The choice is included in both shared links/QR codes and downloaded launch bundles.

To choose a companion from Server or Assembly64, load the primary item first, then browse to the companion file. Use the Add companion button with the link icon beside a matching stereo part or a CRT/REU image. The same button appears in both views when the file can be attached to the loaded item. It restarts the primary item with that companion; clicking the filename keeps its usual playback behavior. These companions retain their server references, so sharing or downloading the complete item does not upload them again.

The Share tab offers two links and QR codes for the same content, companions, selected song, disk autostart selection, and playback settings. One opens the browser emulator; the other starts server-side playback.

For local content, click Upload and update to upload the selected files and generate the links. After upload, the button becomes Update, which saves the current settings without uploading the files again. Hosted collection and Assembly64 content can be shared using its existing server references. Playing individual local files does not upload them, and the Share tab explains when content still needs loading or uploading.

Click Update after changing the settings, companions, or program selected for disk autostart. Repeated updates for an unchanged loaded item keep the same links and QR codes. Changes produce new links; previously shared links retain their original settings.

Use File / Download with companions to download a ZIP to your browser’s usual download location. It contains the primary file, companions, and launch.json describing the settings and autostart selection. Open the ZIP through File / Load content or the playlist picker to restore the complete item; ZIP import uploads the bundle to the server. The normal directory and Assembly64 download buttons still download the original individual file.

Saved links remain usable while the server retains their shared files and referenced collection/Assembly64 content. If you run your own server, saved launches and uploads are stored under <Temp Dir>/playback-shares/. Back up that directory if shares must survive server storage cleanup.

Use a WebAssembly GC build if supported by your browser. The shared-memory build (WASM_GC_SAB) also requires cross-origin isolation on its host; the non-shared build (WASM_GC) is an alternative, with JavaScript builds available as well. Standalone web ZIPs must be served by a web server; opening the HTML directly as a local file is not the supported setup. For embedding or upgrading a website, use the web build’s README.md, UPGRADE.md, and UPGRADE-DEEPSID.md.

Use Settings / Emulation Settings…​ on the desktop or Configuration / Emulation in the browser. The default machine is C64C; choose C64 when a program needs the older CIA and board behavior.

Leave VIC Model at Default to follow that table and the selected video standard/tune detection. Explicit choices are MOS6569R3 or MOS8565 (PAL), and MOS6567R8 or MOS6567R56A (old NTSC). An explicit VIC fixes PAL/NTSC and overrides the video-standard controls and tune detection; return to Default to use automatic video-standard selection again. On the desktop, changing the C64 or VIC model requires restarting JSIDPlay2. In the browser, restart the tune/game after changing either model.

For PAL colors, choose JSIDPlay2 or VICE in the desktop Video Screen’s Monitor Settings, or JSIDPlay2 PAL / VICE-style PAL under browser Configuration / Screen. This choice applies at the next playback start. The VICE-style preset matches VICE 3.10 x64sc’s default PAL colors, using its default MOS8565 palette, gamma 1.00 and default color controls independently of the emulated VIC model. It uses native-resolution PAL filtering without artificial scanlines; NTSC keeps the standard renderer.

Use the song-length database when you want known tunes to finish automatically. PSIDv5’s embedded song length takes precedence when supplied; otherwise the database or configured default length is used. A default length of zero means unlimited playback when no known length is available. Choose Single Song to stay on the selected song, or disable it to continue through a tune’s songs. Use Loop to repeat playback instead of advancing when the selected playback sequence ends.

Silence Timeout ends tunes of unknown length after the configured number of silent seconds; zero disables detection. Find it in desktop Emulation Settings or browser Configuration / Playback. Software playback measures generated SID/FM audio, so continuing register writes do not prevent a silent ending. Changing playback volume does not affect the detector, and manually muting a voice or samples suspends detection. Hardware and Network SID output use register inactivity instead.

Keep automatic SID selection for files that already describe their chips. Stereo Sniffer can detect up to 15 active SIDs in older content; it is independent of PSID64 detection. Additional chips must show sustained voice activity, so volume-only samples or rarely updated held notes can require manual configuration. For manual two/three-SID playback, choose the SID count and addresses, then set the per-chip balance/delay controls. Fake Stereo duplicates a mono tune through multiple SIDs; it does not turn it into a separately composed stereo tune.

SFX Sound Expander provides OPL1 (YM3526) or OPL2 (YM3812) FM sound alongside SID playback. PSIDv5 files can request FM automatically. For older SID+FM files, select the Sound Expander manually; enable it only when needed because FM emulation uses additional CPU time.

Press Record one frame in Raster timeline to record the next complete raster frame. The recorder waits for the observed raster-zero transition and stops automatically after one PAL or NTSC frame. Playback continues; recording does not freeze the machine or turn off Live inspection. Resume first if playback is paused.

Eight sprite lanes show enabled intervals in blue and DMA intervals in turquoise. Orange marks show observed changes to sprite coordinates, expansion, colors, enables and pointers. The VIC lane also shows other stored register and bank changes. DMA means sprite data fetching is active; it does not guarantee opaque or visible pixels. Click a lane to select that hardware sprite and the nearest change, or step through changes using the browser slider or desktop list. The detail shows recorded X/Y, enables, DMA, pointer and bank values at that boundary. This explains multiplexing: the same hardware sprite can be moved and reused several times during one frame.

Timeline selection only reads the recorded log. It does not rewind emulation or replace the independent picture, memory preview or sprite thumbnails. The recording has its own chip, generation and start-time metadata. Save timeline exports it as JSON, separately from Save capture.

Recording is off by default. Only an explicit request schedules half-cycle probes; no recorder or probe is kept running after completion or cancellation. Only changed scalar values are stored, with a hard limit of 8,192 changes. The recorder performs no guest register reads, pixel copies, or periodic memory snapshots. Sprite pointers are side-effect-free previews of the current pointer table, rather than a trace of the VIC’s latched fetches. Equal-value writes are omitted; values are observed after device events at PHI1/PHI2 boundaries, not through write hooks.

Cancel recording retains the available partial history. Freeze or a breakpoint also ends the recording and retains history up to the stop. Incomplete or capped recordings are labeled explicitly, with the unrecorded tail shaded. Hiding the view allows this single recording to finish. Clear releases its data; stop or reset also discards the service’s recorder and retained log. A new recording replaces the previous one.

Choose a condition and press Arm breakpoint. Up to 16 rules may be active; Disarm all removes them. They remain armed when the view is hidden or closed. A hit pauses the emulator inside its execution batch and opens the inspector with the matching capture. Reset or stopping playback disarms the rules.

For collision/DMA masks, $01 selects sprite 0, $08 selects sprite 3, and $FF selects any sprite. Decimal values and hexadecimal values beginning with $ or 0x are accepted. One shot removes the rule on its first hit. A repeating raster rule continues to its next occurrence after Resume. Collision rules observe latch transitions, including CPU reads which clear the latch; they do not infer collisions by intersecting sprite rectangles.

Cycle numbers follow the emulator core’s existing convention: cycles are numbered from 1, and a raster begins at core cycle 10. The capture includes PHI1/PHI2 and absolute emulated time. Breakpoint probes run as separate scheduler events after the relevant device event; they do not stop in the middle of an instruction or reconstruct dot-level history. Raster rules schedule their next position directly. Other state rules check the required phases only while armed, without copying memory or recording history on each check.

Save capture exports versioned JSON with the C64/VIC/clock models, generation, frame, raster, core cycle, phase, trigger ID/type/target/value/mask, previous and observed condition values, register bytes, bus/counter state, and requested memory. The desktop toolbar and browser tab indicate armed rules. The exported capture is diagnostic evidence, not a restorable machine save state.

C64.getInspection() lazily provides the shared InspectionService. Call its methods on the emulation thread; desktop embeddings can use Player.inspect(service → …​) to marshal a request and install the player pause handler. Browser embeddings use js2inspection / SET_INSPECTION. The generated API reference describes actions, masks and acknowledgements. A raw C64 embedding must stop its execution loop when the service pauses; InspectionService.clock(maxEvents) provides a loop which stops inside a batch.

Subscriptions request data groups: 1 state, 2 sprites, 4 characters, 8 screen/color/bitmap memory, and 16 rendered video (default mask 31). Live sampling always omits video. Host control/status responses also omit it; only explicit snapshots, freezes and hits copy pixels. The optional video object contains viewport dimensions, its first raster, beam position, viewport start time, availability status and a committed pixel count. Pixel data uses RGB24_BASE64 and contains only the committed prefix in row order; the uncommitted suffix must be marked as unfinished. A missing video channel is null. Exported pixels are unmodified renderer output; markers and checkerboard are presentation overlays, independently reproducible from the metadata. watchVideo() holds full-frame rendering for a visible view without scheduling snapshots; close its subscription when hidden. Browser embeddings use SHOW / HIDE for that lifecycle, separately from LIVE / OFF memory sampling. One sampler serves their union. Packets are detached from chip state; absent groups are empty arrays, and unavailable mapped bytes are -1. The browser permits one packet in flight, one pending state/hit and one pending timeline result. Live updates cannot discard an undelivered breakpoint hit or completed recording; acknowledgements from older sessions are ignored.

recordTimeline(listener) requests a frame; cancelTimeline(), clearTimeline() and timeline() control or retrieve it. Browser actions are RECORD_TIMELINE, CANCEL_TIMELINE, CLEAR_TIMELINE and GET_TIMELINE. Timeline updates use the existing acknowledged transport with reason: "TIMELINE" and a separate timeline object (or null when cleared); they must not replace the ordinary inspection snapshot. Updates are sent only when waiting, starting or finishing a recording, rather than on every probe or live snapshot. The versioned timeline holds an initial array and ordered changes. Fields 0..63 are stored VIC register bytes, 64 is the DMA mask, 65 the VIC bank and 66..73 current sprite pointer-table bytes. Changes contain half-cycle tick offsets, raster, core cycle, phase, field, previous and new values. Ticks are relative to startTime at the observed raster-zero PHI1; startCycle retains that model’s actual core cycle. A completed frame has cyclesPerLine * rasterLines * 2 ticks.

The inspection service owns sampling, trigger rules, pause state and capture reporting. A small read-only VICInspection adapter accesses existing VIC state; no callbacks are added to VIC rendering/fetch loops or CPU execution. Future chip views can add requested data groups and adapters, and extend the separately enabled, bounded timeline. The timeline records state changes, rather than bus transactions or per-pixel history.

Focused validation and optional UI/performance checks:

The browser check needs Chrome, the four compiled TeaVM backends, and local webjar resources. It checks the actual Vue component and workers, including PAL/old NTSC, hidden-view teardown, pause/resume, exact trigger stops, and phone widths. ui.vic.VICExplorerCheck is an opt-in JavaFX FXML/control check on a working display; it saves English/German screenshots without opening a visible stage. Reports are under target/vic-inspection/. Run the benchmark alone, without concurrent builds. It reports synthetic CPU/VIC work separately for unused, dormant, live+JSON, and armed inspection; presentation and SID audio costs are outside that benchmark. An example run and its limits are recorded in src/test/resources/debug/inspection-performance.txt.

In the following image the general layout of the UI is shown.

The main window is divided into several regions:

Record your favorite SID music to MP3 files.

Record SIDs as MP3 by Command Line

For music, choose Standard latency and reduce video frame rate or disable unused visuals. For games, choose Gaming latency and restart the game. Smaller buffers respond sooner but require the emulator to keep up more consistently. ReSIDfp Circuit, FM, and many-SID tunes need more processing time than ordinary one-SID playback. If a shared-memory build cannot start on a particular host, try the non-shared WebAssembly build.

The browser marks restart-required settings with a yellow warning; restart playback after changing them. For C64/VIC model changes on the desktop, restart the application. PAL color-preset changes apply at the next playback start.

Selecting a local image gives the emulator its contents; it does not grant write access to the original file. Do not treat a browser session or its saved preferences as a persistent copy of disk or expansion RAM. GeoRAM session retention is described under the cartridge controls above.