Stems & Calibration

.gitignore

@@ -50,3 +50,6 @@ sampletones
 *.exe
 *.dll
 *.so
+
+!tests/data/compatibility/**/*.ins
+!tests/data/compatibility/**/*.stn

CHANGELOG.md

@@ -4,7 +4,11 @@
 
 * Added NSF player and export.
 * Added stems conversion: to mix several recordings into one reconstruction.
+* Changed drive to reach for louder instructions while a recording converts; reconvert anything converted at a drive other than `1.00`.
+* Improved clarity of reconstructions.
+* Optimized the size of reconstructions.
 * Bumped the reconstruction data-version to `2.2` with backward compatibility for `2.1`.
+* Bumped the library data-version to `2.1`.
 
 ## v0.3.1 [2026-08-18]
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help setup install system-deps build release run clean pre-commit test test-docs benchmarks lint format
+.PHONY: help setup install system-deps build release run calibration clean pre-commit test test-docs benchmarks lint format
 
 ifeq ($(OS),Windows_NT)
 PYTHON := python
@@ -24,6 +24,7 @@ help:
 	@echo $(Q)  make test        - Run the test suite with coverage$(Q)
 	@echo $(Q)  make test-docs   - Run the doctests$(Q)
 	@echo $(Q)  make benchmarks  - Run the measured-duration suite$(Q)
+	@echo $(Q)  make calibration - Measure reconstruction on the reference sounds; writes the renders and a report$(Q)
 	@echo $(Q)  make clean       - Remove build artifacts and cache files$(Q)
 	@echo $(Q)  make lint        - Run mypy and pylint (ARGS=--mypy or ARGS=--pylint for one of them)$(Q)
 	@echo $(Q)  make format      - Auto-format code (isort, black)$(Q)
@@ -48,6 +49,9 @@ system-deps:
 run:
 	uv run sampletones
 
+calibration:
+	uv run sampletones calibration
+
 clean:
 	$(PYTHON) scripts/clean.py
 

README.md

@@ -6,7 +6,7 @@
 
 <div align="center">
     <img src="https://raw.githubusercontent.com/JakimPL/SampleToNES/main/src/sampletones_assets/icons/sampletones.svg" alt="SampleToNES" width="64">
-    <p><i>SampleToNES</i> v0.3.2</p>
+    <p><i>SampleToNES</i></p>
 </div>
 
 ## Overview
@@ -21,26 +21,31 @@ The core idea is to approximate an audio sample using only the chip's basic osci
 
 A built-in sequencer lets you arrange the reconstructed samples into patterns and play them back inside the application, so you can experiment with the results before exporting the instruments into FamiTracker.
 
-It supports:
+With it you can:
 
-* loading common audio formats: WAV, MP3, FLAC, OGG, AIFF, and AU
-* a wide range of NES frequencies, from 15 Hz to 300 Hz, including the two most common standards:
-    * NTSC (60 Hz)
-    * PAL (50 Hz)
-* various sample rates, from 8000 Hz to 192,000 Hz
-* restricting the reconstruction to a chosen subset of oscillators:
-    * `pulse1`
-    * `pulse2`
-    * `triangle`
-    * `noise`
-* exporting reconstructed audio as FamiTracker `.fti` instruments, Bitphase `.json` instrument presets, `.nsf` programs the NES itself plays, or `.wav`
+* convert your own recordings — WAV, MP3, FLAC, OGG, AIFF or AU — into NES instruments
+* choose which of the four channels each recording may use, and how loud it plays on them
+* arrange the results into a song and play it back in the app
+* export instruments and songs for:
+  * [_FamiTracker_](http://famitracker.com/)
+  * [_Bitphase_](https://bitphase.app/)
+  * `.nsf` program
+  * audio `.wav` file
 
 ## Installation
 
 You can install _SampleToNES_ in three ways:
 
 - **Download a release** for Windows or Linux from the [releases page](https://github.com/JakimPL/SampleToNES/releases), extract it, and start `sampletones`.
-- **Install from PyPI** on Windows, macOS or Linux. You need Python 3.12 or newer:
+- **Install from PyPI** on Windows, macOS or Linux. You need Python 3.12 or newer. On Linux and
+  macOS, install the audio and file dialog libraries first:
+
+  ```sh
+  sudo apt-get install libportaudio2 libasound2 python3-tk    # Debian and Ubuntu
+  brew install portaudio                                      # macOS
+  ```
+
+  Then install the app and start it:
 
   ```sh
   uv tool install sampletones      # or: pipx install sampletones
@@ -53,26 +58,12 @@ An NVIDIA graphics card can speed up conversion. The [installation guide](https:
 
 ## Usage
 
-### Where your files are stored
-
-Your configuration, instruction libraries (`.ins`), and reconstructions (`.stn`) live under your documents folder, in `SampleToNES/`:
-
-- Windows: `C:\Users\<user>\Documents\SampleToNES`
-- Linux: `/home/<user>/Documents/SampleToNES`
-- macOS: `/Users/<user>/Documents/SampleToNES`
-
-### Command line
-
-Every operation is a named command, and `sampletones` alone starts the interface:
-
-```sh
-sampletones run --config <config-path>                            # start with a custom config
-sampletones open <project-path>                                   # start with a project, reconstruction or library loaded
-sampletones convert <audio-path> --config <config-path> -o <out>  # reconstruct a recording without the GUI
-sampletones library --config <config-path>                        # generate an instruction library
-```
+`sampletones` starts the app. Your work is saved in a `SampleToNES` folder inside your documents
+folder.
 
-Run `sampletones --help` for the commands and `sampletones <command> --help` for a command's options. The [command-line guide](https://github.com/JakimPL/SampleToNES/blob/main/docs/guide/command-line.md) explains them.
+Every operation is also a named command — `sampletones convert <audio-path>` reconstructs a
+recording without the interface, for example. Run `sampletones --help` for the list, and see the
+[command-line guide](https://github.com/JakimPL/SampleToNES/blob/main/docs/guide/command-line.md).
 
 ## Documentation
 

docs/api/index.md

@@ -5,29 +5,10 @@ This page is for using _SampleToNES_ as a library in your own Python code. Use i
 Names come from two packages:
 
 - The names in the table below come from `sampletones`: `from sampletones import ...`.
-- The examples also use a few helpers from `sampletones_core`: `write_wave`, `generate_library`, `DEFAULT_CHANNELS`, and the FamiTracker instrument writers. Import them with the full path each example shows.
+- The examples also use a few helpers from `sampletones_core` that are not in the table: `write_wave`, `ensure_library`, `DEFAULT_CHANNELS`, and the FamiTracker instrument writers. Import them with the full path each example shows.
 
 ## Public surface
 
-```python
-from sampletones import (
-    Config,
-    Window,
-    InstructionLibrary,
-    Reconstruction,
-    Reconstructor,
-    ChannelName,
-    Generator,
-    PulseGenerator,
-    TriangleGenerator,
-    NoiseGenerator,
-    Instruction,
-    PulseInstruction,
-    TriangleInstruction,
-    NoiseInstruction,
-)
-```
-
 | Name | Purpose |
 | --- | --- |
 | `Config` | generation configuration; build it with `Config.load(path)` or `Config.default()` |
@@ -51,42 +32,36 @@ The package version is available as `sampletones.__version__`.
 from sampletones import Config, PulseGenerator, PulseInstruction
 from sampletones_core.audio.io import write_wave
 
-# Load configuration
 config = Config.load("config.json")
 
-# Prepare generator and instruction
 generator = PulseGenerator(config)
 instruction = PulseInstruction(on=True, pitch=55, volume=7, duty_cycle=2)
-
-# Generate waveform
 audio = generator(instruction)
 
-# Save audio file
-sample_rate = config.sample_rate
-write_wave("pulse.wav", sample_rate, audio)
+write_wave("pulse.wav", config.sample_rate, audio)
 ```
 
 The output is a single `G2` square wave one frame long.
 
-Each generator keeps an oscillator phase and clock. By default a call renders a standalone waveform and leaves that state where it was; pass `save=True` to advance it into the next call, so a sequence of instructions renders as one continuous signal:
+Each generator keeps an oscillator phase and clock. A call renders a standalone waveform and leaves that state where it was. Pass `save=True` to advance the state into the next call, so a sequence of instructions renders as one continuous signal:
 
 ```python
 audio = generator(instruction, save=True)  # advances the generator state
 ```
 
 ### Generate an instruction library
 
-A reconstruction searches an [instruction library](../formats/instruction-libraries.md) built for its configuration, so the library must exist first. Generate it once for a given config:
+A reconstruction searches an [instruction library](../formats/instruction-libraries.md) built for its configuration by this version of _SampleToNES_, so prepare the library first:
 
 ```python
 from sampletones import Config
-from sampletones_core.headless.library import generate_library
+from sampletones_core.headless.library import ensure_library
 
 config = Config.load("config.json")
-generate_library(config)  # renders every instruction and writes the .ins library
+ensure_library(config)  # builds the .ins library when it is missing or another version built it
 ```
 
-The same step is reached from the application's _Instructions_ tab, or on the command line with `sampletones library --config config.json`.
+The application's _Instructions_ tab and `sampletones library --config config.json` do the same.
 
 ### Reconstruct a sample
 
@@ -97,19 +72,14 @@ from sampletones import Config, Reconstructor
 from sampletones_core.audio.io import write_wave
 from sampletones_core.constants.enums import DEFAULT_CHANNELS
 
-# Load configuration
 config = Config.load("config.json")
 
-# Prepare the reconstructor for the channels the run may use
+# The channels the run may use
 reconstructor = Reconstructor(config, frozenset(DEFAULT_CHANNELS))
 
-# Reconstruct an audio file and save the reconstruction
 reconstruction = reconstructor("sample.wav")
 reconstruction.save("reconstruction.stn")
-
-# Save the reconstruction waveform
-sample_rate = config.sample_rate
-write_wave("reconstruction.wav", sample_rate, reconstruction.approximation)
+write_wave("reconstruction.wav", config.sample_rate, reconstruction.approximation)
 ```
 
 ### Load a reconstruction
@@ -139,4 +109,4 @@ for channel, features in reconstruction.export().items():
     write_fti(f"{channel.value}.fti", instrument)
 ```
 
-This writes one `.fti` per channel, named after the channel. A complete FamiTracker `.ftm` module is assembled from a project in the application, not from a single reconstruction — see [FamiTracker formats](../formats/famitracker.md).
+This writes one `.fti` per channel, named after the channel. A `.ftm` module comes from a project in the application. See [FamiTracker formats](../formats/famitracker.md).