Metadata-Version: 2.5
Name: sampletones
Version: 0.3.2
Summary: Approximate audio samples with the NES 2A03 oscillators and export them as FamiTracker instruments
Project-URL: Homepage, https://github.com/JakimPL/SampleToNES
Project-URL: Repository, https://github.com/JakimPL/SampleToNES
Project-URL: Documentation, https://github.com/JakimPL/SampleToNES/tree/main/docs
Project-URL: Changelog, https://github.com/JakimPL/SampleToNES/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/JakimPL/SampleToNES/issues
Author-email: "Jakim (Stage Magician)" <jakimpl@gmail.com>
License-Expression: MIT
License-File: LICENSE
License-File: THIRD-PARTY-NOTICES.md
Keywords: 2a03,audio,chiptune,dsp,famitracker,nes,resynthesis,tracker
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: anytree<3,>=2.12
Requires-Dist: dearpygui<3,>=2.3
Requires-Dist: jeepney<1,>=0.8; sys_platform == 'linux'
Requires-Dist: librosa<0.12,>=0.11
Requires-Dist: msgpack<2,>=1.0
Requires-Dist: numpy<3,>=2.0
Requires-Dist: pebble<6,>=5.0
Requires-Dist: py65<2,>=1.2
Requires-Dist: pyaudio<0.3,>=0.2.14
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: pytaskbar<0.2,>=0.1.1; platform_system == 'Windows'
Requires-Dist: pywin32>=306; platform_system == 'Windows'
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: rich<16,>=13.0
Requires-Dist: scipy<2,>=1.13
Requires-Dist: screeninfo<0.9,>=0.8
Requires-Dist: soundfile<0.14,>=0.13
Requires-Dist: tqdm<5,>=4.66
Provides-Extra: build
Requires-Dist: pyinstaller<7,>=6.21; extra == 'build'
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x[ctk]<15,>=14; extra == 'gpu'
Provides-Extra: gpu-cuda11
Requires-Dist: cupy-cuda11x<14,>=13; extra == 'gpu-cuda11'
Requires-Dist: nvidia-cublas-cu11; (sys_platform == 'linux') and extra == 'gpu-cuda11'
Requires-Dist: nvidia-cuda-nvrtc-cu11; (sys_platform == 'linux') and extra == 'gpu-cuda11'
Requires-Dist: nvidia-cuda-runtime-cu11; (sys_platform == 'linux') and extra == 'gpu-cuda11'
Description-Content-Type: text/markdown

# SampleToNES

[![PyPI](https://img.shields.io/pypi/v/sampletones.svg)](https://pypi.org/project/sampletones/)
[![Python](https://img.shields.io/pypi/pyversions/sampletones.svg)](https://pypi.org/project/sampletones/)
[![License](https://img.shields.io/pypi/l/sampletones.svg)](https://github.com/JakimPL/SampleToNES/blob/main/LICENSE)

<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></p>
</div>

## Overview

_SampleToNES_ (`sampletones`) is a desktop tool for people writing music for the NES 2A03 sound chip, mainly in [_FamiTracker_](http://famitracker.com/) or [_Bitphase_](https://bitphase.app/).

<div align="center">
    <img src="https://raw.githubusercontent.com/JakimPL/SampleToNES/main/docs/images/sampletones.webp" alt="SampleToNES" width="760">
</div>

The core idea is to approximate an audio sample using only the chip's basic oscillators — two pulse channels, a triangle, and noise — **without any DPCM samples**.

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.

With it you can:

* 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. 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
  sampletones
  ```

- **Run from source** with Python 3.12 or newer and [uv](https://docs.astral.sh/uv/): `make system-deps`, `make setup`, then `make run`.

An NVIDIA graphics card can speed up conversion. The [installation guide](https://github.com/JakimPL/SampleToNES/blob/main/docs/guide/installation.md) covers the system libraries each way needs, GPU support, and building a standalone app yourself.

## Usage

`sampletones` starts the app. Your work is saved in a `SampleToNES` folder inside your documents
folder.

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

The [user guide](https://github.com/JakimPL/SampleToNES/tree/main/docs/guide) explains how to use the app, step by step. The app opens it in your browser from **Help ▸ Documentation**. The rest of [`docs/`](https://github.com/JakimPL/SampleToNES/tree/main/docs) covers the reconstruction algorithms, the file formats, the Python API and the developer notes.

## License

_SampleToNES_ is released under the [MIT License](https://github.com/JakimPL/SampleToNES/blob/main/LICENSE).

The bundled fonts are third-party works under their own licenses (SIL Open Font License 1.1
and the Bitstream Vera license) and are not covered by the MIT License.

The standalone bundles on the [releases page](https://github.com/JakimPL/SampleToNES/releases)
additionally contain the Python runtime and every dependency, including several LGPL-licensed
libraries. [`THIRD-PARTY-NOTICES.md`](https://github.com/JakimPL/SampleToNES/blob/main/THIRD-PARTY-NOTICES.md)
lists everything they redistribute and what its license requires; the full license texts are in
[`THIRD-PARTY-LICENSES.txt`](https://github.com/JakimPL/SampleToNES/blob/main/THIRD-PARTY-LICENSES.txt)
and ship inside each bundle.
