JakimPL · JakimPL · Aug 25, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -78,4 +78,7 @@ jobs:
         run: uv run python -m pytest src/ --doctest-modules --no-cov
 
       - name: Run the unit and integration suites with coverage
-        run: uv run python -m pytest -n auto --cov
+        run: uv run python -m pytest -n auto --cov --ignore=tests/benchmarks
+
+      - name: Run the benchmarks
+        run: uv run python -m pytest tests/benchmarks --no-cov
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -73,6 +73,14 @@ repos:
         pass_filenames: false
         verbose: true
 
+      - id: shortcut-actions
+        name: shortcut actions
+        entry: uv run scripts/checks/shortcut_actions.py
+        language: system
+        files: (\.py|^src/sampletones_config/keybindings/.*\.yaml)$
+        pass_filenames: false
+        verbose: true
+
       - id: mypy
         name: mypy
         entry: uv run mypy

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,75 +1,79 @@
-# SampleToNES
-
-## v0.3.2
-
-* Added NSF player and export.
-
-## v0.3.1 [2026-08-18]
-
-* Added support to [Bitphase](https://github.com/paator/bitphase).
-* Fixed arpeggio editing shifting a sample's pitch permanently.
-* Enhanced application options:
-    * Display settings
-    * Theme selector
-    * Keybinding settings
-* Bumped the reconstruction data-version to `2.1`.
-* Improved Sequencer module playback.
-* Added song export to WAV/MP3.
-* Added tracker selection operations.
-* Added a _SampleToNES_ logo.
-
-## v0.3.0 [2026-07-31]
-
-* Added a _Sequencer_ view with FamiTracker-style patterns.
-* Added project export in a FamiTracker-compatible format.
-* Improved matching algorithms and extended available methods (`LogFFT`, `CQT`).
-* Improved the general layout of the application.
-* Changed the internal file formats (`.stn`, `.ins`).
-* Switched to `uv` as the package manager.
-* Detect the NVIDIA driver at setup and install the matching _CuPy_ build automatically, on Linux and Windows.
-
-## v0.2.3 [2026-01-09]
-
-* Improved the application's graphical interface.
-* Added the main page with filesystem explorer.
-* Added editing and saving reconstructions.
-* Added audio settings panel.
-* Implemented instructions library autogeneration.
-* Simplified instructions library tree.
-
-## v0.2.2 [2025-11-21]
-
-* Added GPU support via _CuPy_.
-* Fixed generation bugs.
-* Made minor visual improvements.
-* Improved code quality.
-* Released the application.
-
-## v0.2.1 [2025-11-17]
-
-* Optimized the output file structure.
-* Improved application error handling.
-* Enhanced task processing communication with the GUI.
-* Fixed installer bugs.
-* Created a Python package and an application installer via _PyInstaller_.
-
-## v0.2.0 [2025-11-08]
-
-* Created a graphical interface for the application.
-* Added application content:
-    * Instruction instruction data explorer
-    * Audio reconstruction viewer
-* Included instruction data creation and converter windows.
-* Added audio graphs and spectrum plots.
-* Implemented audio playback.
-
-## v0.1.0 [2025-10-23]
-
-* Added spectral features and FFT windows for the sample approximator.
-* Included mixer levels for adjusting the general amplitude of sound.
-* Created an instruction instruction data for reconstruction optimization.
-* Added instruction data and generation configurations.
-
-## v0.0.1 [2025-09-24]
-
-First version of _SampleToNES_, containing basic reconstruction scripts and all 2A03 generators.
+# SampleToNES
+
+## v0.3.2
+
+* Added NSF player and export.
+* Added stems conversion: mix several recordings into one reconstruction
+* Matched each stem against its own recording, so a stem plays what was recorded on it
+* Added a per-source channel cap
+* Bumped the reconstruction data-version to `2.2` with backward compatibility for `2.1`.
+
+## v0.3.1 [2026-08-18]
+
+* Added support to [Bitphase](https://github.com/paator/bitphase).
+* Fixed arpeggio editing shifting a sample's pitch permanently.
+* Enhanced application options:
+    * Display settings
+    * Theme selector
+    * Keybinding settings
+* Bumped the reconstruction data-version to `2.1`.
+* Improved Sequencer module playback.
+* Added song export to WAV/MP3.
+* Added tracker selection operations.
+* Added a _SampleToNES_ logo.
+
+## v0.3.0 [2026-07-31]
+
+* Added a _Sequencer_ view with FamiTracker-style patterns.
+* Added project export in a FamiTracker-compatible format.
+* Improved matching algorithms and extended available methods (`LogFFT`, `CQT`).
+* Improved the general layout of the application.
+* Changed the internal file formats (`.stn`, `.ins`).
+* Switched to `uv` as the package manager.
+* Detect the NVIDIA driver at setup and install the matching _CuPy_ build automatically, on Linux and Windows.
+
+## v0.2.3 [2026-01-09]
+
+* Improved the application's graphical interface.
+* Added the main page with filesystem explorer.
+* Added editing and saving reconstructions.
+* Added audio settings panel.
+* Implemented instructions library autogeneration.
+* Simplified instructions library tree.
+
+## v0.2.2 [2025-11-21]
+
+* Added GPU support via _CuPy_.
+* Fixed generation bugs.
+* Made minor visual improvements.
+* Improved code quality.
+* Released the application.
+
+## v0.2.1 [2025-11-17]
+
+* Optimized the output file structure.
+* Improved application error handling.
+* Enhanced task processing communication with the GUI.
+* Fixed installer bugs.
+* Created a Python package and an application installer via _PyInstaller_.
+
+## v0.2.0 [2025-11-08]
+
+* Created a graphical interface for the application.
+* Added application content:
+    * Instruction instruction data explorer
+    * Audio reconstruction viewer
+* Included instruction data creation and converter windows.
+* Added audio graphs and spectrum plots.
+* Implemented audio playback.
+
+## v0.1.0 [2025-10-23]
+
+* Added spectral features and FFT windows for the sample approximator.
+* Included mixer levels for adjusting the general amplitude of sound.
+* Created an instruction instruction data for reconstruction optimization.
+* Added instruction data and generation configurations.
+
+## v0.0.1 [2025-09-24]
+
+First version of _SampleToNES_, containing basic reconstruction scripts and all 2A03 generators.
diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
-.PHONY: help setup install build release system-deps run clean pre-commit test \
-	ftm-samples icons check-import-boundary check-tag-names check-unused-tags \
-	check-language-keys check-palette-colors calibration lint pylint mypy format
+.PHONY: help setup install build release system-deps run clean pre-commit test benchmarks \
+	ftm-samples nsf-samples nsf-render compression-report icons player check-import-boundary check-tag-names check-unused-tags \
+	check-language-keys check-palette-colors check-shortcut-actions calibration lint pylint mypy format
 
 ifeq ($(OS),Windows_NT)
 ifeq ($(MSYSTEM),)
@@ -66,11 +66,16 @@ help:
 	@echo $(Q)  make setup       - Set up development environment (uv); GPU auto-detected, GPU=0 forces CPU$(Q)
 	@echo $(Q)  make pre-commit  - Install pre-commit hooks$(Q)
 	@echo $(Q)  make system-deps - Install system packages required to build and run (Debian-based, or Homebrew on macOS)$(Q)
-	@echo $(Q)  make build       - Compile standalone executable (respects current deployment config)$(Q)
-	@echo $(Q)  make release     - Compile standalone executable with the release deployment config$(Q)
+	@echo $(Q)  make build       - Compile standalone executable (development deployment config: DEBUG, strict history)$(Q)
+	@echo $(Q)  make release     - Compile standalone executable with the release deployment config (INFO, self-healing history)$(Q)
 	@echo $(Q)  make test        - Run unit tests with coverage$(Q)
+	@echo $(Q)  make benchmarks  - Run the measured-duration suite on its own$(Q)
 	@echo $(Q)  make ftm-samples - Emit example .ftm files to build/ftm via the integration suite$(Q)
+	@echo $(Q)  make nsf-samples - Emit example .nsf files to build/nsf via the integration suite$(Q)
+	@echo $(Q)  make nsf-render  - Render the .nsf files in build/nsf to waves with ffmpeg$(Q)
+	@echo $(Q)  make compression-report - Measure the song codec into build/compression$(Q)
 	@echo $(Q)  make icons       - Generate the icon suite into src/sampletones_assets/icons$(Q)
+	@echo $(Q)  make player      - Assemble the NES player driver with cc65$(Q)
 	@echo $(Q)  make calibration - Score the reconstruction corpus; the report lands in Documents/SampleToNES/calibration$(Q)
 	@echo $(Q)  make clean       - Remove build artifacts and cache files$(Q)
 	@echo $(Q)  make lint        - Run linting (pylint, mypy)$(Q)
@@ -107,13 +112,30 @@ pre-commit:
 test:
 	$(call script,dev/tests)
 
+benchmarks:
+	uv run python -m pytest tests/benchmarks --no-cov
+
 ftm-samples: export SAMPLETONES_FTM_OUTPUT_DIR := build/ftm
 ftm-samples:
 	uv run python -m pytest tests/integration/famitracker
 
+nsf-samples: export SAMPLETONES_NSF_OUTPUT_DIR := build/nsf
+nsf-samples:
+	uv run python -m pytest tests/integration/nsf
+
+nsf-render: nsf-samples
+	uv run scripts/nsf_render.py
+
+compression-report: export SAMPLETONES_COMPRESSION_OUTPUT_DIR := build/compression
+compression-report:
+	uv run python -m pytest tests/integration/nsf/test_compression_report.py
+
 icons:
 	uv run --group assets python scripts/assets/icons.py
 
+player:
+	uv run scripts/player.py
+
 check-import-boundary:
 	uv run scripts/checks/import_boundary.py --all
 
@@ -129,6 +151,9 @@ check-language-keys:
 check-palette-colors:
 	uv run scripts/checks/palette_colors.py
 
+check-shortcut-actions:
+	uv run scripts/checks/shortcut_actions.py
+
 calibration:
 	uv run scripts/calibration.py
 

diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@ It supports:
     * `pulse2`
     * `triangle`
     * `noise`
-* exporting reconstructed audio as FamiTracker `.fti` instruments, Bitphase `.json` instrument presets, or `.wav`
+* exporting reconstructed audio as FamiTracker `.fti` instruments, Bitphase `.json` instrument presets, `.nsf` programs the NES itself plays, or `.wav`
 
 ## Installation
 

diff --git a/conftest.py b/conftest.py
@@ -1,25 +1,27 @@
-import importlib.util
 from pathlib import Path
 from typing import Final, Optional, Tuple
 
-JEEPNEY_MODULE: Final[str] = "jeepney"
+from sampletones_shared.utils.system.modules import JEEPNEY_MODULE, module_available
 
-PORTAL_PATHS: Final[Tuple[str, ...]] = (
+JEEPNEY_PATHS: Final[Tuple[str, ...]] = (
     "src/sampletones_application/utils/file_dialogs/backends/portal",
+    "src/sampletones_shared/utils/system/reveal/file_manager1.py",
     "tests/unit/sampletones_application/utils/file_dialogs/backends/portal",
     "tests/unit/sampletones_application/utils/file_dialogs/test_selection.py",
+    "tests/unit/sampletones_shared/utils/system/reveal/test_file_manager1.py",
 )
 
-PORTAL_LIBRARY_INSTALLED: Final[bool] = importlib.util.find_spec(JEEPNEY_MODULE) is not None
+JEEPNEY_INSTALLED: Final[bool] = module_available(JEEPNEY_MODULE)
 
 
 def pytest_ignore_collect(collection_path: Path) -> Optional[bool]:
     """
     Keeps collection to the modules the running platform imports.
 
-    ``jeepney`` is declared for Linux alone, so what speaks to the desktop portal is collected
-    where that library is installed. The behaviour those modules describe belongs to the Linux
-    desktop, and the Linux runs of the suite cover it.
+    ``jeepney`` is declared for Linux alone, so what speaks D-Bus — the desktop portal's file
+    dialogs and the ``FileManager1`` reveal backend — is collected where that library is
+    installed. The behavior those modules describe belongs to the Linux desktop, and the Linux
+    runs of the suite cover it.
 
     Args:
         collection_path: The file or directory pytest is about to look into.
@@ -28,11 +30,11 @@ def pytest_ignore_collect(collection_path: Path) -> Optional[bool]:
         Optional[bool]: ``True`` for a path that stays out of collection, ``None`` to leave the
             choice with pytest.
     """
-    if PORTAL_LIBRARY_INSTALLED:
+    if JEEPNEY_INSTALLED:
         return None
 
     root = Path(__file__).parent
-    if any(collection_path.is_relative_to(root / path) for path in PORTAL_PATHS):
+    if any(collection_path.is_relative_to(root / path) for path in JEEPNEY_PATHS):
         return True
 
     return None
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -13,7 +13,7 @@ from sampletones import (
     InstructionLibrary,
     Reconstruction,
     Reconstructor,
-    GeneratorName,
+    ChannelName,
     Generator,
     PulseGenerator,
     TriangleGenerator,
@@ -31,8 +31,8 @@ from sampletones import (
 | `Window` | analysis window derived from a config (`Window.from_config(config)`) |
 | `InstructionLibrary` | the library of candidate instructions a reconstruction searches |
 | `Reconstructor` | runs a reconstruction: `Reconstructor(config)("sample.wav")` |
-| `Reconstruction` | the result of a reconstruction — its approximation audio, per-generator instructions, and the config used |
-| `GeneratorName` | enum naming the four channels: `pulse1`, `pulse2`, `triangle`, `noise` |
+| `Reconstruction` | the result of a reconstruction — its approximation audio, per-channel instructions, and the config used |
+| `ChannelName` | enum naming the four channels: `pulse1`, `pulse2`, `triangle`, `noise` |
 | `Generator` | shared base class of the oscillator generators |
 | `PulseGenerator`, `TriangleGenerator`, `NoiseGenerator` | render one channel's waveform from an instruction |
 | `Instruction` | shared base class of the per-frame channel instructions |
@@ -110,7 +110,7 @@ write_wave("reconstruction.wav", sample_rate, reconstruction.approximation)
 
 ### Load a reconstruction
 
-`Reconstruction.load` reads a saved `.stn` back into a `Reconstruction`, carrying its approximation, per-generator instructions, and config:
+`Reconstruction.load` reads a saved `.stn` back into a `Reconstruction`, carrying its approximation, per-channel instructions, and config:
 
 ```python
 from sampletones import Reconstruction
@@ -120,7 +120,7 @@ reconstruction = Reconstruction.load("reconstruction.stn")
 
 ### Export instruments
 
-`Reconstruction.export` returns the per-channel [features](../formats/instruction-libraries.md), one entry per generator, and each set saves as a FamiTracker `.fti` instrument:
+`Reconstruction.export` returns the per-channel [features](../formats/instruction-libraries.md), one entry per channel, and each set saves as a FamiTracker `.fti` instrument:
 
 ```python
 from sampletones import Reconstruction

diff --git a/docs/concepts/calibration.md b/docs/concepts/calibration.md
@@ -12,13 +12,13 @@ and runs as a script:
 ```
 python scripts/calibration.py [--config <base>] [--methods fft,cqt]
     [--perceptual-exponents 0.5,1.0] [--temporal-weights 0.1,0.3]
-    [--generators pulse1,triangle,noise]
+    [--channels pulse1,triangle,noise]
 ```
 
 The base configuration comes from `--config` when given; otherwise the saved
 application configuration is used, so a run inherits the current app settings —
 sample rate, gamma, selector and the rest. The channel set is the exception:
-calibration pins the generators itself (`--generators`, by default pulse 1 +
+calibration pins the channels itself (`--channels`, by default pulse 1 +
 triangle + noise), so every run reconstructs with an explicitly chosen channel
 set and results stay comparable across machines.