JakimPL · JakimPL · Aug 18, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 7, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -41,13 +41,16 @@ jobs:
       - name: Run every pre-commit hook
         run: uv run pre-commit run --all-files --show-diff-on-failure --color always
 
+      - name: Check the committed icons match the mark
+        run: uv run pre-commit run icons --all-files --hook-stage pre-push --color always
+
   tests:
     name: Tests (${{ matrix.os }}, py${{ matrix.python }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         python: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v7
@@ -62,6 +65,12 @@ jobs:
         if: runner.os == 'Linux'
         run: bash scripts/linux/build/dependencies.sh
 
+      - name: Install system libraries (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          bash scripts/macos/build/dependencies.sh
+          bash scripts/macos/build/build_env.sh >> "$GITHUB_ENV"
+
       - name: Install the development environment
         run: uv sync --group dev
 

diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
@@ -58,6 +58,10 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python: ["3.12", "3.13"]
     steps:
+      - uses: actions/checkout@v7
+        with:
+          path: repository
+
       - uses: actions/download-artifact@v8
         with:
           name: dist
@@ -74,10 +78,8 @@ jobs:
       - name: Install PortAudio (macOS)
         if: runner.os == 'macOS'
         run: |
-          brew install portaudio
-          prefix="$(brew --prefix portaudio)"
-          echo "CFLAGS=-I${prefix}/include" >> "$GITHUB_ENV"
-          echo "LDFLAGS=-L${prefix}/lib" >> "$GITHUB_ENV"
+          bash repository/scripts/macos/build/dependencies.sh
+          bash repository/scripts/macos/build/build_env.sh >> "$GITHUB_ENV"
 
       - name: Install the wheel and check the entry point
         shell: bash
@@ -124,7 +126,7 @@ jobs:
             venv_python=.venv-build/bin/python
           fi
           "$venv_python" -m pip install --upgrade pip
-          "$venv_python" -m pip install ".[build]"
+          "$venv_python" -m pip install ".[build]" --group assets
 
       - name: Build the bundle (Linux)
         if: runner.os == 'Linux'

diff --git a/.gitignore b/.gitignore
@@ -4,25 +4,20 @@ __pycache__/
 .ipynb_checkpoints/
 .mypy_cache/
 .pytest_cache/
+.ruff_cache/
 .venv/
 .venv-build/
 .vscode/
 
-bin/
-build/
 dist/
 wheels/
-!scripts/**/build/
+/bin/
+/build/
 
 sampletones
 !src/sampletones
 !tests/sampletones
 
-**/*.idea
-**/*.vscode/**
-**/*.ipynb_checkpoints/**
-**/*__pycache__/**
-
 *.pyc
 *.pyo
 *.coverage

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -51,10 +51,18 @@ repos:
 
       - id: tag-names
         name: tag names
-        entry: uv run scripts/checks/tag_names.py
+        entry: uv run scripts/checks/tag_names.py --all
         language: system
         types: [python]
-        files: ^src/sampletones_application/tags/
+        pass_filenames: false
+        verbose: true
+
+      - id: palette-colors
+        name: palette colors
+        entry: uv run scripts/checks/palette_colors.py
+        language: system
+        files: (^src/sampletones_application/.*\.py|^src/sampletones_config/.*\.yaml)$
+        pass_filenames: false
         verbose: true
 
       - id: language-keys
@@ -83,6 +91,16 @@ repos:
         require_serial: true
         exclude: ^(tests/)
 
+      - id: icons
+        name: icons
+        entry: uv run python scripts/assets/icons.py
+        language: system
+        files: ^src/sampletones_assets/(icons|mark)/
+        pass_filenames: false
+        verbose: true
+        stages:
+          - pre-push
+
       - id: pytest
         name: pytest
         entry: make test

diff --git a/.pylintrc b/.pylintrc
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,15 @@
 
 * 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]
 

diff --git a/LICENSE b/LICENSE
@@ -22,7 +22,9 @@ SOFTWARE.
 
 ---
 
-The MIT license above covers the SampleToNES source code only.
+The MIT license above covers the SampleToNES source code and the application
+icons under `src/sampletones_assets/icons/`, which are drawn from the mark
+declared in `src/sampletones_assets/mark/`.
 
 Font files bundled under `src/sampletones_assets/fonts/` are the work of third
 parties and remain under their own licenses (SIL Open Font License 1.1 and the

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 check-import-boundary check-tag-names check-unused-tags \
-	check-language-keys calibration lint pylint mypy format
+	ftm-samples icons check-import-boundary check-tag-names check-unused-tags \
+	check-language-keys check-palette-colors calibration lint pylint mypy format
 
 ifeq ($(OS),Windows_NT)
 ifeq ($(MSYSTEM),)
@@ -43,12 +43,14 @@ endif
 BUILD_COMMAND := $(RUN_SCRIPT) $(BUILD_SCRIPT)
 RELEASE_COMMAND := $(RUN_SCRIPT) $(BUILD_SCRIPT) --release
 SYSTEM_DEPS_COMMAND := bash scripts/linux/build/dependencies.sh
+SETUP_ENV :=
 
 ifeq ($(UNAME_S),Darwin)
-	MACOS_SOURCE_ONLY := bash scripts/macos/source_only.sh
-	BUILD_COMMAND := $(MACOS_SOURCE_ONLY) 'make build'
-	RELEASE_COMMAND := $(MACOS_SOURCE_ONLY) 'make release'
-	SYSTEM_DEPS_COMMAND := $(MACOS_SOURCE_ONLY) 'make system-deps'
+	MACOS_NO_BUNDLE := bash scripts/macos/build/no_bundle.sh
+	BUILD_COMMAND := $(MACOS_NO_BUNDLE) 'make build'
+	RELEASE_COMMAND := $(MACOS_NO_BUNDLE) 'make release'
+	SYSTEM_DEPS_COMMAND := bash scripts/macos/build/dependencies.sh
+	SETUP_ENV := ARCHFLAGS="-arch $(shell uname -m)"
 endif
 
 GPU ?= auto
@@ -63,19 +65,22 @@ help:
 	@echo $(Q)Available targets:$(Q)
 	@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)$(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 test        - Run unit tests with coverage$(Q)
 	@echo $(Q)  make ftm-samples - Emit example .ftm files to build/ftm via the integration suite$(Q)
+	@echo $(Q)  make icons       - Generate the icon suite into src/sampletones_assets/icons$(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)
 	@echo $(Q)  make format      - Auto-format code (isort, black)$(Q)
 	@echo $(Q)  make run         - Run SampleToNES application$(Q)
 
 setup:
-	uv sync --group dev $(if $(GPU_EXTRA),--extra $(GPU_EXTRA),)
-	uv tool install --force $(if $(GPU_EXTRA),".[$(GPU_EXTRA)]",.)
+	$(SETUP_ENV) uv sync --group dev $(if $(GPU_EXTRA),--extra $(GPU_EXTRA),)
+	$(MAKE) icons
+	$(SETUP_ENV) uv tool install --force $(if $(GPU_EXTRA),".[$(GPU_EXTRA)]",.)
 
 install:
 	$(MAKE) setup
@@ -106,6 +111,9 @@ ftm-samples: export SAMPLETONES_FTM_OUTPUT_DIR := build/ftm
 ftm-samples:
 	uv run python -m pytest tests/integration/famitracker
 
+icons:
+	uv run --group assets python scripts/assets/icons.py
+
 check-import-boundary:
 	uv run scripts/checks/import_boundary.py --all
 
@@ -118,8 +126,11 @@ check-unused-tags:
 check-language-keys:
 	uv run scripts/checks/language_keys.py
 
+check-palette-colors:
+	uv run scripts/checks/palette_colors.py
+
 calibration:
-	uv run scripts/calibration.py --all
+	uv run scripts/calibration.py
 
 lint:
 	$(call script,dev/lint)

diff --git a/README.md b/README.md
@@ -4,10 +4,16 @@
 [![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">
+</div>
+
 ## Overview
 
 _SampleToNES_ (`sampletones`) is a desktop tool for people writing music for the NES 2A03 sound chip, mainly in [_FamiTracker_](http://famitracker.com/).
 
+<img src="https://raw.githubusercontent.com/JakimPL/SampleToNES/main/docs/images/sampletones.png" alt="SampleToNES" width="640">
+
 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.
@@ -57,11 +63,12 @@ To install with GPU support, request the `gpu` extra (see [GPU acceleration](#gp
 uv tool install "sampletones[gpu]"
 ```
 
-On Linux, audio playback and file dialogs rely on system libraries that cannot come from
-PyPI. Install them first:
+On Linux and macOS, audio playback and file dialogs rely on system libraries that come from
+the platform's package manager. Install them first:
 
 ```sh
 sudo apt-get install libportaudio2 libasound2 python3-tk    # Debian/Ubuntu
+brew install portaudio                                      # macOS
 ```
 ### Building the executable yourself
 

diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md
@@ -35,12 +35,16 @@ are not used in any SampleToNES component name.
 
 Every dependency is installed separately by `pip`/`uv` from PyPI and imported at runtime.
 
-Most dependencies are permissively licensed (MIT, BSD, Apache-2.0, ISC). Two are under the
-GNU Lesser General Public License — [Pebble](https://pypi.org/project/Pebble/) (LGPL-3.0,
-a direct dependency) and [soxr](https://pypi.org/project/soxr/) (LGPL-2.1-or-later, a
-transitive dependency of `librosa`) — and two, `certifi` and `tqdm`, are under MPL-2.0.
-
-All four are used as unmodified, separately installed libraries loaded dynamically at
+Most dependencies are permissively licensed (MIT, BSD, Apache-2.0, ISC). Three carry code
+under the GNU Lesser General Public License — [Pebble](https://pypi.org/project/Pebble/)
+(LGPL-3.0, a direct dependency), [soxr](https://pypi.org/project/soxr/)
+(LGPL-2.1-or-later, a transitive dependency of `librosa`), and
+[soundfile](https://pypi.org/project/soundfile/) (BSD-3-Clause itself, a direct
+dependency, whose wheel carries the libsndfile shared library under LGPL-2.1-or-later with
+LAME and mpg123 statically linked into it) — and two, `certifi` and `tqdm`, are under
+MPL-2.0.
+
+All of them are used as unmodified, separately installed libraries loaded dynamically at
 import time. No LGPL- or MPL-licensed code is copied into the wheel or the sdist, so the
 MIT License applies to the PyPI package without further obligation.
 
@@ -105,3 +109,18 @@ The published bundles are **CPU-only**: CuPy, the CUDA runtime and the NVIDIA li
 are proprietary, and their EULA reserves redistribution to NVIDIA. GPU acceleration comes
 from installing _SampleToNES_ from PyPI with the `gpu` extra, which fetches CuPy and the
 CUDA components from their publishers straight to your machine.
+
+## Build-time tooling
+
+The application icons are drawn by `sampletones_assets.mark` and rasterized with
+[Pillow](https://pypi.org/project/Pillow/), which is under the
+[MIT-CMU license](https://github.com/python-pillow/Pillow/blob/main/LICENSE). Pillow belongs
+to the `assets` dependency group alone, so `pip`/`uv` installs it on the machine that
+generates the icons: it stays out of the wheel's dependency set, and PyInstaller is told to
+leave it out of the bundles. Both distributions carry the finished icon files, so Pillow's
+attribution clause — a condition on redistributing Pillow itself — rests with the build
+environment.
+
+The icons (`sampletones.svg`, `sampletones.png` and the multi-resolution `sampletones.ico`)
+are original _SampleToNES_ artwork and fall under the MIT License together with the rest of
+the source.
diff --git a/docs/concepts/reconstruction.md b/docs/concepts/reconstruction.md
@@ -242,12 +242,12 @@ reconstruction and the original can be shown and played on a common scale.
 
 ## Appendix — key parameters and where things live
 
-Default configuration (44.1 kHz, 30 Hz change rate, channels pulse 1 + triangle +
+Default configuration (44.1 kHz, 60 Hz change rate, channels pulse 1 + triangle +
 noise):
 
 | parameter                | default | notes                                              |
 |--------------------------|---------|----------------------------------------------------|
-| frame length             | 1470    | `sample_rate / nes_frequency`, ~33 ms              |
+| frame length             | 735     | `sample_rate / nes_frequency`, ~17 ms              |
 | spectrum method          | `cqt`   | `fft` / `logfft` / `cqt`                            |
 | `transformation_gamma`   | 0       | 0 = power spectrum, 100 = log                       |
 | spectral / temporal weight | 0.8 / 0.2 | criterion blend                                 |