SampleToNES documentation

SampleToNES rebuilds an audio sample from the sound channels of the NES's 2A03 chip: two pulse waves, a triangle and noise. You can arrange the results into a song. You can export them to FamiTracker, to Bitphase, or as an .nsf program the NES plays.

The sections below are grouped by what you want to do. The guide needs no prior knowledge. The concepts and formats sections assume you have used the application. The API and development sections are for programmers.

The guide walks through the application from installation onward.

• Installation — the ways to install it, and GPU acceleration.
• Getting started — your first reconstruction and your first song.
• The interface — the four tabs, the menus and the keyboard shortcuts.
• Converting audio — the Main tab: adding recordings, choosing channels and running a conversion.
• Working with a reconstruction — the Reconstruction tab: listening, editing instruments and exporting.
• The sequencer — the tracker: writing a song from samples and instruments, exporting it and rendering it to audio.
• Command line — running without the graphical interface.
• Where your files live — the folders and file types SampleToNES uses.
• Configuration — the settings you can change, and where.

The concepts section explains the ideas behind the reconstruction. You can read it without the source code.

• Reconstruction algorithms — how a sample becomes a stream of NES instructions.
• Stems reconstruction — how the channels are shared between several stems.
• Instruction library — the catalog of NES sounds the search draws from.
• Song compression — how a song fits into the space an NES program has for it.
• Song timing — how a tempo becomes the ticks each row lasts.
• Project — a song and the reconstructions it is built from.

The tools section covers the commands that measure SampleToNES or produce examples. Each page says how to run the command with no options, what it writes and every custom use.

• Calibration — how well the reconstruction reproduces reference sounds, with every reconstruction written out to listen to.
• Tracker playback check — whether a song exported to a tracker plays there the way the app plays it, tick by tick.

The formats section documents the files SampleToNES reads and writes.

• Instruction libraries — the .ins candidate catalog.
• Reconstructions — the .stn reconstruction data.
• Projects — the .stp project bundle.
• FamiTracker export — the .fti instrument and .ftm module formats.
• Bitphase export — the .btp document and .json instrument preset formats.
• NSF export — the .nsf program the console plays, and the song block inside it.
• Configuration file — the config.json structure.

The Python API page shows how to use sampletones as a library, with worked examples.

The development section is for contributors. The pages at its top cover the whole repository. The pages about the graphical application and about releases each have a directory.

• Architecture — the application's layers and the contracts between them.
• Package layers — the packages of the repository, and the order they import each other in.
• Tooling — the sampletones command, the tools package, the checkout units and the bootstrap scripts, with what each runs on and what it may import.
• Assets — the unit that makes the repository's own content: the icon suite, the demo tree, and the pictures of the application in the guide and the README.
• Coding guidelines — conventions for the codebase.
• Writing the documentation — who each document is written for, and how it reads.
• Console player — the 6502 driver an .nsf carries, the codec that fits a song beside it, and how both are verified.
• Progress — how a long operation reports progress, within one process and across worker processes.
• Bugs and to-dos — the working ledger of known gaps.

The application

• Undo engine — the design of undo and redo.
• Sequencer blocks — the rules copy, cut, paste and delete follow on both grids.
• Keyboard and actions — how a press reaches behavior, and how an action is declared and shown.
• Identifier vocabularies — the keys display text is looked up by, and the tags DearPyGui knows a widget by.
• Colors and palettes — how a color is written, composed, and handed to DearPyGui.
• The render thread — how work reaches DearPyGui from another thread, and what each crossing costs.
• Dialogs — how a dialog gets its size, where it opens, and when it reaches the screen.
• Playback — the audio transport shared by every view, and rendering the song to a file.
• Reconstruction browser — how a reconstructions directory becomes the tree both browser tabs show, and what narrows it.
• Stems in the application — the Stems card, and what an edit or a removal does to the per-frame record.
• Editing the open reconstruction — how the Reconstructions tab takes the reader's edits one step at a time, and what waits for them.
• Screen scenarios — tests that run the whole application on a display and press its controls the way a user does.
• Configuration — how the YAML configuration package is laid out.

Releases

• Data compatibility — how a file saved by an older version is upgraded to the current format when it loads.
• Dependencies — the libraries SampleToNES builds on.

The glossary defines the terms the other pages link to: NES hardware, the reconstruction pipeline and tracker concepts.