Corrscope: turning chiptune WAV files into oscilloscope videos

A video renderer for chiptune, not a general waveform viewer

Corrscope is a Python program that renders oscilloscope views of WAV files recorded from chiptune, which the readme defines as game music from retro sound chips. The output is a video of a scope trace moving in time with the audio, the kind of thing a chiptune artist would put on a video or a music channel.

The scope of the tool is narrow in a good way. It is not an audio editor, not a spectrum analyser and not a general-purpose waveform visualiser. It takes audio that came out of a chip or an emulator, and draws it the way an oscilloscope would have drawn the original signal.

That framing explains the rest of the design. Chiptune audio is often dry, mono or near-mono, and it is often the result of FM synthesis with several operators layered on top of each other. The resulting waveform does not look like a clean sine, and a scope that simply triggers on a rising edge loses its place constantly. Corrscope's answer to that is the feature the project is known for.

The audience is therefore quite specific: chiptune artists making videos, and the people who want to visualise retro game audio in the style the hardware would have produced. Documentation lives at corrscope.github.io/corrscope, and sample results are published on the author's YouTube channel.

Waveform correlation is what keeps a complex wave on screen

Corrscope uses waveform correlation to track complex waves, including SNES and Sega Genesis and FM synthesis, which jump around on other oscilloscope programs.

The mechanism is the trigger. A scope needs a consistent point in the waveform to start each sweep from, otherwise the trace jitters and the picture becomes unreadable. A simple scope triggers on an amplitude threshold, an edge, or a zero crossing, and any of those fail on a layered FM signal, where the instantaneous value depends on how the operators happen to be summing.

Correlation instead compares the incoming signal against a reference shape and starts the sweep where the signal best matches that shape. Because the reference is a pattern rather than a level, it survives the parts of the signal where the raw value wanders, so the trace stays stable through a passage that a level-triggered scope would lose. That is the whole reason the project exists as a separate program rather than a configuration of a generic one.

The readme is candid that this is the differentiator, and the readme is also candid that the program is in semi-active development, that it basically works, that bugs will be fixed as they are discovered, and that features will be added and feature requests may be accepted on a case by case basis.

Installing: pick pipx, pip, or uv, and the right Qt extra

The dependency list is short, and one entry dominates it. FFmpeg is the only stated external dependency, and it is what makes playback previews and video rendering possible.

Python is required, and the readme asks for 3.8 or above, while the pyproject in the repository currently states requires-python = ">=3.10, <4". The pyproject version is also ahead of the last release, at 0.11.1-pre against the published 0.11.0, so the development branch and the released package differ.

The recommended route is pipx, since it creates an isolated environment per program, and the author describes it as the most reliable in practice, with the caveat that it can run into issues after upgrading system Python in place:

pipx install "corrscope[qt5]"

The Qt binding is a choice rather than a detail. On Linux, installing with the qt6 extra adds support for native Qt 6 themes:

pipx install --system-site-packages "corrscope[qt6]"

On Apple Silicon, the readme says to run pipx install "corrscope[qt6]" instead. On FreeBSD there is a longer path involving py39-qt5 and py39-ruamel.yaml from the ports tree, plus ffmpeg from the ports tree with the SDL option enabled to get previews working.

The plain pip route is documented too, with pip3 install --user "corrscope[qt5]", and the author is direct about the trade-off: pip installs into a per-user Python environment, so each program you install influences the packages seen by other programs.

For running from source, the project uses uv, with a sync step that selects the extra:

cd path/to/corrscope
uv sync --extra qt5
# On Apple Silicon, instead run `uv sync --extra qt6`.
uv run corr (args)

The corr command: split, edit the YAML, then play or render

The command line workflow is a four step tutorial in the readme, and it is worth following literally the first time.

Step one is to create a YAML project from a set of channel WAV files, with the master audio track given by the -a or --audio option and the -w flag:

corr split*.wav --audio master.wav -w

That produces a file called master.yaml. Step two is to edit master.yaml to change settings, which is the point of the format: the project is a text file, so a scope setup can be edited in a text editor or kept in version control rather than reconfigured through a window every time.

Step three is playback, which needs ffmpeg:

corr master.yaml -p/--play

Step four is rendering and encoding a video, also needing ffmpeg:

corr master.yaml -r/--render file.mp4

Other file extensions are supported for the render output, so this is not hard-wired to MP4.

The entry point in the pyproject is corr = "corrscope.cli:main", and the commands are implemented with click, with numpy doing the signal work and matplotlib rendering the traces. That dependency set is what makes the project installable as a normal Python package rather than a script with vendored libraries.

The GUI edits the same project, and the two front ends share a file

Corrscope also has a windowed interface, and it is worth understanding that it works on the same YAML project file rather than on a separate format.

The tutorial is short. You launch the GUI with corrscope.exe to create a new project, or with corrscope.exe followed by a file.yaml to open an existing one. On the right side of the window you use Browse to pick a master audio file and Add to add the WAV files you want as scope channels. Global settings live on the left, per-channel settings on the right. Then you play, or render to MP4 or another format via the toolbar or the menu, and rendering requires ffmpeg.

So the division of labour is: the CLI generates and plays the project, the GUI is where you adjust the visuals, and the YAML file is the shared state. A workflow that starts from the command line and tweaks in the window keeps the configuration as a diffable artefact.

On Windows, the prebuilt binaries are distributed as 7z archives on the releases page, and you run corrscope.exe directly. The readme notes one gotcha there: if the program does not start, you may need to install the latest Visual C++ Redistributable.

Where Corrscope is the wrong tool, and the Mac caveats

The limitations are specific and worth reading before you commit.

The first is scope. This is a chiptune renderer. A general audio visualisation, or a DAW, or a spectrum analyser does the job for other audio, and Corrscope has no claim on those. The readme's own framing, that other oscilloscope programs lose the complex waves, also implies the comparison set is other scope programs rather than general tools.

The second is the ffmpeg dependency for anything beyond static rendering. Playback and video encoding both need it, and the readme lists it as the single external dependency. On FreeBSD the readme adds the detail that previews need ffmpeg installed from the ports tree with the SDL option enabled, which is the kind of detail that only appears when the author has actually set it up that way.

The third is the Mac behaviour, and the readme does not hide it. Preview audio can cut out, because previewing sends video frames to ffplay, which opens a player window and plays synchronised audio, and on an M1 MacBook Air running macOS 12.3, switching windows can make ffplay stutter and stop playing audio until the preview is restarted. There is no fix for this at the moment. Rendering does not stutter on M1, because neither Corrscope nor ffmpeg is affected by app switching or App Nap. Separately, Gatekeeper can refuse to open a rendered file with an unidentified developer error, and the workaround is to try opening it again, after which the error does not reappear.

The Android instructions are labelled experimental, and the author says plainly that they have not been tested on a blank slate installation.

BSD licensing, a 2025 release, and pushes in 2026

The project is released under the BSD-2-Clause licence, and the pyproject names nyanpasu64 as the author with a tuta.io contact address. The repository is not archived, and the last push was on 2026-09-22, so the code is still receiving work.

The releases are slower than the pushes. The most recent tags are 0.11.0 from 2025-05-22, 0.10.1 from 2024-09-23 and 0.10.0 from 2024-07-09, while the pyproject on the development branch already reads 0.11.1-pre. The readme describes the state as semi-active development, with bugs fixed as they are discovered and features handled case by case, and support offered through Discord or the issue tracker using the Support/feedback template, with clean pull requests accepted.

The build system is hatchling, and the repository carries a uv.lock, a pyinstaller spec file and a build_pyinstaller.py script, which is how the Windows binaries are produced. Tests use pytest with pytest-mock, hypothesis for property-based testing, pytest-cases and delayed-assert, and the code is formatted with Black at a line length of 88, with a pre-commit hook available to apply it.

One loose end worth noting for anyone pinning versions: the readme says Python 3.8 or above, the pyproject requires 3.10 or above, and the readme documents the pipx and pip routes for releases while the source route requires uv. Those three statements are the installation reality, and the pyproject is the one the package manager will enforce.

Editorial conclusion

Corrscope is a good fit for a chiptune musician or video maker who wants an oscilloscope view that stays locked to complex FM and SNES waves, and it is a poor fit for general audio visualisation, for a headless server without ffmpeg, or for a pipeline that needs a stable command line contract. Before adopting it, install ffmpeg and the right Qt extra for your platform, run corr split on a short sample to see whether the trigger holds on your tracks, and decide between the corr command and the GUI based on whether you want a YAML project file you can edit.

Frequently asked questions

Official sources

1. corrscope/corrscope on GitHub
2. License: BSD-2-Clause
3. Project website
4. README
5. Releases