Stems & Converter Improvement

.pre-commit-config.yaml

@@ -49,6 +49,14 @@ repos:
         pass_filenames: false
         verbose: true
 
+      - id: rendered-literals
+        name: rendered literals
+        entry: uv run scripts/checks/rendered_literals.py
+        language: system
+        files: ^tests/.*\.py$
+        pass_filenames: false
+        verbose: true
+
       - id: tag-names
         name: tag names
         entry: uv run scripts/checks/tag_names.py --all

Makefile

@@ -1,5 +1,5 @@
 .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 \
+	ftm-samples nsf-samples nsf-render compression-report icons player check-import-boundary check-tag-names check-unused-tags check-rendered-literals \
 	check-language-keys check-palette-colors check-shortcut-actions calibration lint pylint mypy format
 
 ifeq ($(OS),Windows_NT)
@@ -113,7 +113,7 @@ test:
 	$(call script,dev/tests)
 
 benchmarks:
-	uv run python -m pytest tests/benchmarks --no-cov
+	uv run python -m pytest tests/benchmarks --no-cov -s
 
 ftm-samples: export SAMPLETONES_FTM_OUTPUT_DIR := build/ftm
 ftm-samples:
@@ -145,6 +145,9 @@ check-tag-names:
 check-unused-tags:
 	uv run scripts/checks/unused_tags.py
 
+check-rendered-literals:
+	uv run scripts/checks/rendered_literals.py
+
 check-language-keys:
 	uv run scripts/checks/language_keys.py
 

docs/api/index.md

@@ -30,7 +30,7 @@ from sampletones import (
 | `Config` | generation configuration; build it with `Config.load(path)` or `Config.default()` |
 | `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")` |
+| `Reconstructor` | runs a reconstruction: `Reconstructor(config, channels)("sample.wav")` |
 | `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 |
@@ -92,12 +92,13 @@ With a library in place for the configuration:
 ```python
 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
-reconstructor = Reconstructor(config)
+# Prepare the reconstructor for the channels the run may use
+reconstructor = Reconstructor(config, frozenset(DEFAULT_CHANNELS))
 
 # Reconstruct an audio file and save the reconstruction
 reconstruction = reconstructor("sample.wav")

docs/concepts/reconstruction.md

@@ -274,7 +274,9 @@ below that is room the matching leaves unused, and material that was never in A=
 temperament — most recordings of most instruments — sits somewhere inside it.
 
 `sampletones_core.reconstructions.reconstructor.refinement` spends that room, after the decoder has
-settled which note each frame plays and before the frames are rendered.
+settled which note each frame plays and before the frames are rendered. It spends it where the run
+asks: a stem entry names the channels it carries toward its own recording, so one recording's bass
+line can land on its exact tuning while another's lead keeps the grid.
 
 ### 6.1 Reading rather than searching
 
@@ -304,14 +306,14 @@ frames with no pitch to read.
 
 ### 6.2 Landing the note, and holding it
 
-A reading becomes a bend through the generator, which owns the divider geometry: `bend_towards`
+A reading becomes a bend through the generator, which owns the divider geometry: `bend_toward`
 answers with the divider steps that land the note nearest the frequency read, bounded by
 `bend_range` — **half the gap to each neighboring note**. That bound is what leaves the refined
 pitches gapless: note *n* covers `[(tₙ + tₙ₊₁) / 2, (tₙ + tₙ₋₁) / 2]`, and those windows tile the
 divider range exactly, so every divider the notes span is reachable and none is claimed twice.
 
 A bend that followed every reading exactly would jitter, and jitter is more audible than the tuning
-it chases. So the per-frame proposals are settled by a change-penalised walk, the same shape the
+it chases. So the per-frame proposals are settled by a change-penalized walk, the same shape the
 Viterbi decoder settles a note contour with: the cost of a bend is how far it stands from that
 frame's reading, plus a toll on changing at all. The states a frame may take are the bends its
 neighborhood proposed together with no bend, which keeps the walk to a handful of states even where
@@ -329,14 +331,19 @@ a tenth or more, since the reading needs a handful of bins per frame and the tra
 every bin the spectrum covers. Restricting it to the bins the chosen notes actually name is the
 work `docs/development/bugs-and-todos.md` records under **Features**.
 
-A frame makes no proposal where it rests, where its channel is not pitched — the noise channel's
-sixteen periods have no finer grid — or where its reading falls below the confidence threshold. A
-conversion that bent no note records both bend dimensions as ones the channel governs, so it writes
-the same instrument it wrote before the feature existed.
+A frame makes no proposal where it rests, where the stem holding it leaves that channel out, where
+its channel is not pitched — the noise channel's sixteen periods have no finer grid — or where its
+reading falls below the confidence threshold. A conversion that bent no note records both bend
+dimensions as ones the channel governs, so it writes the instrument an unrefined run writes.
+
+Which recordings are carried, and on which channels, each stem entry states for itself in
+`bends` — a subset of the channels it occupies, and of the three that load a divider. A channel a
+stem leaves out keeps the note the matching chose, and a stem carrying nothing at all is never
+read, so the transform is spent only where a bend comes of it. The settings below shape a bend
+once it is asked for, and hold for a whole run.
 
 | parameter | default | notes |
 |---|---|---|
-| `generation.refinement.enabled` | on | acts only where the run renders the chosen instructions |
 | `generation.refinement.confidence` | 0.15 | the share of a frame's energy its harmonics must hold |
 | `generation.refinement.change_weight` | 2.0 | divider steps of reading error worth avoiding one change |
 | `generation.refinement.window` | 4 | the frames on either side whose readings a frame may settle on |
@@ -383,7 +390,7 @@ noise):
 | spectral / temporal weight | 0.8 / 0.2 | criterion blend                                 |
 | spectral distance        | β-divergence | also `squared`, `absolute`                     |
 | selector                 | Viterbi | `greedy` / `viterbi`                                |
-| pitch refinement         | on      | bends each note onto the divider the source sounds  |
+| pitch refinement         | per stem | bends each note onto the divider the source sounds  |
 | normalize / quantize     | on / off | input preprocessing                                |
 
 Package map:

docs/concepts/stems.md

@@ -134,13 +134,20 @@ single-sample pipeline always did.
 A request becomes jobs through `reconstructions.converter`: a `ConversionPlan`
 answers with the `ConversionJob`s it divides into, resolved against the
 configuration the run uses. `GroupConversion` mixes the recordings it is given
-into one job, and `DirectoryConversion` scans a folder into one single-source job
-per audio file. `ReconstructionConverter` runs those jobs across its worker pool
+into one job; `BatchConversion` gives each gathered recording a job of its own,
+carrying the setup that recording's own row holds and the folder whose tree its
+reconstruction mirrors; and `DirectoryConversion` scans a folder into one
+single-source job per audio file, which is what the command line converts a
+directory as. `ReconstructionConverter` runs those jobs across its worker pool
 and reports the reconstructions written.
 
-`StemsConfig` (`reconstructor/stems/configs/`) is the setup: the entries with
-their ids and channels, the precedence hierarchy and its mode, and the channel
-cap. It validates its own consistency — unique ids, a hierarchy naming every
+`StemsConfig` (`reconstructor/stems/configs/`) is the setup: the entries, the
+precedence hierarchy and its mode, and the channel cap. An entry is an id and the
+`StemSettings` its recording is converted with — the channels it may occupy, and
+which of those it carries toward the divider it really sounds. A further
+per-recording choice is a field on those settings, which is what lets the list a
+reader sets a run up in, the entry the run records, and a later reader of that
+record all state the same thing. It validates its own consistency — unique ids, a hierarchy naming every
 entry exactly once, a cap of at least one — so an inconsistent setup can be
 neither built nor stored, and it derives the views the run reads (`entries_by_id`,
 `covered_channels`, `frame_budget`).