flipSID 0.3.0
======================================================================

flipSID by Alumni: a small, fast player for Commodore 64 SID music. It
plays through emulation (reSIDfp, classic reSID and the original
resid-fp) and through real SID chips: Ultimate devices over the network
and HardSID USB devices (the 4U, tested; the UPlay and the Uno,
untested).

  Download:  https://flipsid.thealumni.fi/

  Version:   0.3.0 (3fe60736d4, built 2026-11-03)
  Platform:  linux-x86_64
  By:        Alumni (https://thealumni.fi/)
  Code:      https://gitlab.com/dahliazone/c64/flipsid
  Copyright: Copyright (C) 2026 Max A. Vilkki a.k.a. codise
  License:   GPL-2.0-or-later (see COPYING.txt)
  Source:    flipSID-0.3.0-source.zip, beside this package


Features
--------

Playback

  - Three emulation engines, switchable per tune: reSIDfp (the
    default), classic reSID 1.0, and Antti Lankila's original resid-fp
    with the community's measured filter curve presets.
  - Real SID chips: Ultimate devices (1541 Ultimate-II+, Ultimate 64)
    over the network, and HardSID USB devices (the 4U; the UPlay and
    the Uno untested), with a socket per SID for 2SID tunes and mixed
    chip models, and several units at once.
  - Named SIDs: give each chip a name and notes, choose the SIDs a
    tune, subtune or playlist entry plays on, and keep spare chips in
    the SID Chips window.
  - Song ends from the song lengths, with silence detection and a play
    forever mode; seeking, subtunes, and a subtune from the file name
    (Commando.3.sid).
  - Fade-outs: tunes fade out over their last few seconds. Changing the
    tune or pressing Stop fades out quickly too.
  - Software-controlled mixer (Behringer X Air, tried on an XR18): its
    channel's fader fades with the tunes, so real SIDs fade out too.
    The row shows the fader in dB, with a mute and manual control.
  - Graphs of the filter curves, to compare chips and presets.

Library

  - Browses and searches the High Voltage SID Collection: title,
    author, released, path, STIL and the BUGlist, with filters and
    sortable columns, and subtunes with their STIL names, covers and
    artists.
  - Downloads HVSC for you on the first start, and updates it to a new
    release in place, keeping your own folders beside it.
  - Song lengths from Songlengths.md5, with your own lengths on top.
  - Works without HVSC too, or with only Songlengths.md5 and STIL.txt:
    open or drop any .sid file.

Profiles and playlists

  - SID profiles: one complete sound each (engine, chip model, filter
    and more). A tune gets its profile from its chip, and you can
    override the chip or the profile per tune or per playlist entry.
  - Several playlists in tabs, with drag and drop, play modes (repeat,
    shuffle), a filter, colour markers, Liked Songs, and M3U and JSON
    import and export. Each playlist remembers where listening stopped.
  - Stock playlists to start with: nine of HVSC tunes, from the Epic
    C64 SID Collection to ZOO 2026's 2SID picks.
  - Tunes are identified by their HVSC MD5, so playlists survive a
    moved or updated collection.

Interface

  - A dense, dockable workspace: Browser, Search, Playlist, Tune Info,
    Engine and Output.
  - Themes with an editor, and your own banner image.
  - Fast, smooth GPU rendering of the UI using OpenGL.
  - Renders only when something changes, with no busy loops, to keep
    power use low.


Getting started
---------------

flipSID isn't signed by Apple or Microsoft yet, so the system warns
about it the first time:

  macOS     If it says Apple could not verify flipSID is free of
            malware, click Done, open System Settings > Privacy &
            Security, click "Open Anyway" beside the note about flipSID
            and confirm. If it says flipSID "is damaged and can't be
            opened" instead, open Terminal, type  xattr -cr  and a space,
            drag flipSID.app onto the window (that types its path),
            press Return, and open the app again.
  Windows   If SmartScreen says "Windows protected your PC", click
            "More info", then "Run anyway".

Start flipsid. The first time, flipSID asks where your SID files are:

  - Use a folder you have: HVSC's C64Music folder, or any folder of
    .sid files.
  - Download HVSC: the High Voltage SID Collection, over 60,000 tunes
    with their song lengths and notes. About 85 MB comes down and
    unpacks to about 380 MB. Tunes can be played while it downloads.
  - Skip: flipSID works without a collection too. Open a tune with
    Ctrl+O, or drop .sid files and folders on the window.

File > HVSC... shows the collection's release, checks for a new one,
and updates it in place: HVSC's own folders are replaced, anything else
of yours at the top of the collection is kept. With "Check for new HVSC
releases" ticked, flipSID asks the HVSC server about once a week and
says in the status bar when a new release is out. Nothing is downloaded
without a click.


Keys
----

  Space             play / pause
  Escape            stop
  Left / Right      previous / next subtune
  Shift+Left/Right  seek 10 seconds back / forward
  L                 like or unlike the subtune that plays (Liked Songs)
  F                 play forever (no song ends)
  Tab               the next panel
  Ctrl+O            open a tune
  Ctrl+F            search the library
  Ctrl+W            close the playlist tab in front
  Ctrl+,            settings
  Ctrl+Q            quit

On macOS, Cmd takes the place of Ctrl.


What is in this package
-----------------------

  flipsid           the app
  themes/           the built-in themes, with their fonts and licenses
  70-hardsid.rules  lets your user open a HardSID (Real SID chips)
  licenses/         the licenses of the libraries and fonts flipSID uses
  CHANGELOG.txt     what changed in each release
  COPYING.txt       the GNU General Public License, version 2
  README.txt        this file


The C64 ROMs (KERNAL, BASIC and CHARGEN) are copyrighted and not
included. Most tunes play without them; BASIC tunes and a few others
don't. To play those, set a folder with the ROMs in Settings > C64 ROMs,
for example the ROM folder of an installed VICE.


Where flipSID keeps its files
-----------------------------

Settings, SID profiles, playlists and the log (logs/flipsid.log):

  Windows   %APPDATA%\flipSID
  macOS     ~/Library/Application Support/flipSID
  Linux     ~/.local/share/flipSID (or $XDG_DATA_HOME/flipSID)

The library's index cache, rebuilt whenever it is missing:

  Windows   %LOCALAPPDATA%\flipSID
  macOS     ~/Library/Caches/flipSID
  Linux     ~/.cache/flipSID (or $XDG_CACHE_HOME/flipSID)

HVSC downloaded by flipSID goes, unless you choose another folder, to
%LOCALAPPDATA%\flipSID\C64Music on Windows and to C64Music in the
settings folder elsewhere. Removing flipSID: delete this folder (or the
app) and the folders above.


Requirements
------------

  Windows   Windows 10 or later, 64-bit (x64). No runtime to install.
  macOS     macOS 11 or later, Apple silicon or Intel.
  Linux     a distribution from about 2020 on, 64-bit.

A graphics driver with OpenGL 3.3 is needed on every platform.


Real SID chips
--------------

  Ultimate devices (Ultimate 64, 1541 Ultimate-II+): add the device in
  the Output panel by its network address. Playback goes over the
  network; the device can't pause.

  HardSID USB: the 4U is supported and tested on Windows, macOS and
  Linux. The UPlay and the Uno are supported but untested: nobody has
  played one with flipSID yet, so reports are welcome.

  Add the unit in the Output panel. When the system refuses to open it,
  its row says so, and its "Fix..." button shows the steps below (also
  Help > HardSID USB Help...).

  If the computer's audio keeps dropping out and the HardSID slows
  down (the status bar says so): the 4U reserves part of its USB bus,
  and another USB device that streams on the same USB controller (a
  second HardSID, a sound card, headset, microphone or webcam) may not
  get enough; on Windows the second of the two to start is refused
  instead. Plug one of them into a port on another controller (back
  ports instead of front ones), or that device into a USB 2.0 hub.
  Two HardSIDs: each on its own controller, or each behind its own
  USB 2.0 hub.
  Or, to listen to the HardSID only, turn off "Play through this
  computer" in the Output panel: then no sound card is used at all.

  macOS     Nothing to set up.

  Linux     A udev rule gives the logged-in user the unit. Run these in
            a terminal, one at a time (or copy 70-hardsid.rules from
            this package to /etc/udev/rules.d/), then press Test on the
            HardSID's row; still refused: replug the unit.

    echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="6581", ATTR{idProduct}=="858[0-2]", TAG+="uaccess"' | sudo tee /etc/udev/rules.d/70-hardsid.rules
    sudo udevadm control --reload-rules
    sudo udevadm trigger --subsystem-match=usb --attr-match=idVendor=6581

            The same on Arch, Debian, Ubuntu, Fedora and openSUSE. Without
            systemd-logind (Alpine, Void), write MODE="0666" in place of
            TAG+="uaccess": every user may then open the unit.

  Windows   The unit needs the WinUSB driver: uninstall the vendor
            driver in Device Manager ("Delete the driver software"
            ticked) and restart, then bind WinUSB to the HardSID with
            Zadig (https://zadig.akeo.ie), once for each model. Not
            tested with flipSID yet.

  A mixer that fades real SIDs: real chips don't hear flipSID's
  fade-outs, so a Behringer X Air (XR12, XR16, XR18, MR18; tried on an
  XR18) can fade the input channel they play into. Add it in the Output
  panel (Add device... > Mixer) by its network address and channel.
  Manual control on its row leaves the fader to you.


Command line
------------

  flipsid [--subtune N] [file.sid]
  flipsid --version | --help | --self-test

A file name like Commando.3.sid plays subtune 3.


Bugs, ideas and source code
---------------------------

Report bugs and suggest features at
https://gitlab.com/dahliazone/c64/flipsid/-/issues (Help > Report a Bug
or Idea... in the app), with the log file (see above) for a bug if you
can.

If flipSID crashes, please say what you were doing and send:

  - the log: logs/flipsid.log in the settings folder above, and
    flipsid.log.1 too if flipSID was started again since (Help > About
    flipSID... has a button that opens the folder);
  - on macOS, the crash report as well: the newest flipSID-<date>.ips in
    ~/Library/Logs/DiagnosticReports (in Finder: Go > Go to Folder...).
    It's also behind "Report..." in the dialog macOS shows.

The source code of this build comes beside this package, as

  flipSID-0.3.0-source.zip

flipSID's own, with every library it is built from in lib/, at the
commits it was built from, so it builds as it is (README.md in it says
how). The libraries' licenses are in licenses/.


Support
-------

flipSID's development was kindly supported by Finer Things Software
(http://finerthings.software/). To support flipSID, try out their
products.


Thanks
------

Thanks to Tero "Terwiz" Tervala for inspiring this project in the first
place. The Alumni logo in the Alumni theme is Copyright Tero "Terwiz"
Tervala and is used with permission.

flipSID stands on more than thirty years of SID emulation work: Dag Lem
(reSID), Antti Lankila (resid-fp), Leandro Nini (reSIDfp, libsidplayfp),
Simon White and Michael Schwendt (libsidplay2), the VICE team, the HVSC
crew, Stone Oakvalley (SOASC), the people who measured their chips'
filter curves, and the authors of SDL, Dear ImGui, ImPlot, miniaudio,
yyjson, libebur128, libusb, libarchive and XZ Utils. Thanks to Grue and
Zamdee for testing it and for their feedback and suggestions. The full
list is in README.md in the source.
