fourier-samples 0.1.0__tar.gz

fourier_samples-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: Bug report
+description: Something Fourier Samples did wrong, or a crash
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Please leave out personal details (names, paths with your user
+        name, your library's pack names) and don't attach audio you don't have the rights to
+        share. A security problem goes to the private form instead: Security tab, "Report a
+        vulnerability".
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: The command you ran and what it did. Paste the error or traceback if there was one.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: If it happens with `fourier demo` too, say so; that's the easiest case to reproduce.
+  - type: input
+    id: version
+    attributes:
+      label: fourier --version
+      placeholder: fourier (Fourier Samples) 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS and version
+      placeholder: macOS 15.3 (Apple silicon), Ubuntu 24.04, ...
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.8"
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: fourier doctor output
+      description: The output of `fourier doctor` (edit out paths you'd rather not share).
+      render: text
+  - type: input
+    id: device
+    attributes:
+      label: Device and firmware
+      description: If it's about a render or sync.
+      placeholder: The device and its OS or firmware version

fourier_samples-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: A question, or help getting started
+    url: https://github.com/bvk7787/fourier-samples/discussions/categories/q-a
+    about: Ask in Discussions (Q&A). Include what you ran and what `fourier doctor` says.
+  - name: Share a device profile you made
+    url: https://github.com/bvk7787/fourier-samples/discussions/categories/show-and-tell
+    about: Profiles from `fourier devices new`, tried on your sampler, before they're cited from its manual.

fourier_samples-0.1.0/.github/ISSUE_TEMPLATE/device_request.yml

@@ -0,0 +1,46 @@
+name: Device request
+description: Ask for a profile for a sampler Fourier Samples doesn't render for yet
+labels: [device]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A profile cites the device's manual for every value (docs/device-profiles.md). The
+        details below are what a profile needs; if you can draft one yourself, a pull request
+        is welcome. Until then, `generic_44k` or `generic_48k` renders a usable library.
+  - type: input
+    id: device
+    attributes:
+      label: Device
+      placeholder: Maker and model
+    validations:
+      required: true
+  - type: input
+    id: manual
+    attributes:
+      label: Manual
+      description: A link to the maker's current manual (PDF), and its firmware or OS version.
+    validations:
+      required: true
+  - type: textarea
+    id: format
+    attributes:
+      label: Sample format and limits
+      description: |
+        What you know, with manual pages if you have them: sample rate and bit depth, mono or
+        stereo, file formats, length or slice limits, path or file-name length limits, folder
+        depth or files per folder, and storage size.
+    validations:
+      required: true
+  - type: input
+    id: load
+    attributes:
+      label: How samples get onto it
+      description: An SD card or USB drive mounted on the computer, a transfer app, copying into a project, or something else.
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: Folder layout the device expects, how its browser sorts, quirks you've hit.

fourier_samples-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: An idea for Fourier Samples
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What you're trying to do
+      description: The problem or the workflow, not only the solution you have in mind.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you'd like
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you've tried or considered

fourier_samples-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# GitHub Actions only: the Python dependencies are pinned in uv.lock and updated by hand
+# (the synthetic golden's audio holds only for the locked versions).
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

fourier_samples-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What this changes
+
+<!-- What and why. Link the issue if there is one. -->
+
+## Checks
+
+- [ ] Tests run (`pytest -q -n auto tests`), and a behavior change comes with a test
+- [ ] For a curation change: the synthetic golden (`python tests/golden/synthetic_build.py /tmp/syn --check`); if the output is meant to change, regenerated with `--update` and explained above
+- [ ] For a command, option or help-text change: `python tests/test_cli_tree.py --write`
+- [ ] `ruff check src tests`
+- [ ] Docs updated (README, CLAUDE.md, docs/) where the behavior they describe changed
+- [ ] No personal data and no real samples: fixtures use generated audio and invented names (Acme, Northwind, ...), and no real vendor, pack or person is named
+- [ ] For a device profile: every value cites a manual page or is marked a convention, and what I checked on the hardware is described above

fourier_samples-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# Actions minutes are free on a public repository and metered on a private one, where the
+# maintainer runs the same checks locally: every job skips while the repository is private.
+jobs:
+  test:
+    name: test (${{ matrix.os }}, ${{ matrix.python-version }})
+    if: ${{ !github.event.repository.private }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    continue-on-error: ${{ matrix.os == 'windows-latest' }}   # Windows: best effort for now
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+        exclude:
+          - os: macos-latest
+            python-version: "3.11"
+          - os: windows-latest
+            python-version: "3.11"
+        include:
+          - os: ubuntu-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      # the versions in uv.lock: the synthetic golden's audio holds only for these
+      # (CLAP and torch left out: the tests use a stand-in)
+      - name: Install (locked versions; core + dev)
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip uv
+          uv export --frozen --no-hashes --extra dev --no-emit-project > "$RUNNER_TEMP/requirements.lock.txt"
+          pip install -r "$RUNNER_TEMP/requirements.lock.txt"
+          pip install -e . --no-deps
+      - name: Lint
+        run: ruff check src tests
+      - name: Tests
+        run: pytest -q -n auto tests      # one worker per CPU (pytest-xdist; conftest.py isolates each)
+      - name: Synthetic golden build
+        shell: bash
+        run: python tests/golden/synthetic_build.py "$RUNNER_TEMP/synthetic" --check
+      # the variants below test the pipeline, not the Python version: 3.13 runs the golden only
+      - name: Without Sononym, without Live, without both
+        if: matrix.python-version != '3.13'
+        shell: bash
+        run: |
+          python tests/golden/synthetic_build.py "$RUNNER_TEMP/no-sononym" --without sononym
+          python tests/golden/synthetic_build.py "$RUNNER_TEMP/no-live" --without ableton
+          python tests/golden/synthetic_build.py "$RUNNER_TEMP/neither" --without sononym,ableton
+      - name: Each preset builds and passes verify
+        if: matrix.python-version != '3.13'
+        shell: bash
+        run: |
+          python tests/golden/synthetic_build.py "$RUNNER_TEMP/breaks-acid" --preset breaks-acid
+          python tests/golden/synthetic_build.py "$RUNNER_TEMP/balanced" --preset balanced
+      - name: A small library's master scales to it
+        if: matrix.python-version != '3.13'
+        shell: bash
+        run: python tests/golden/synthetic_build.py "$RUNNER_TEMP/scaled" --scale --preset balanced
+      - name: An interrupted build resumes to the same result
+        if: matrix.python-version != '3.13'
+        shell: bash
+        run: python tests/golden/synthetic_build.py "$RUNNER_TEMP/resume" --check --interrupt KICKS,PADS,VOX
+
+  package:
+    # what `pip install` gives a user: the sdist and wheel build, their metadata passes twine,
+    # and the wheel installed with its declared dependencies (no checkout, no [clap]) runs
+    name: package (build, install, run)
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Build the sdist and wheel
+        run: |
+          python -m pip install --upgrade pip uv
+          uv build
+          ls -l dist
+      - name: Check the metadata
+        run: uvx twine check --strict dist/*
+      - name: Check what the wheel holds
+        run: |
+          python -m zipfile -l dist/*.whl > "$RUNNER_TEMP/wheel.txt"
+          for f in fourier/__main__.py fourier/demo.py fourier/_config/tunables.yaml \
+                   fourier/_config/devices/m8_tracker.yaml licenses/LICENSE licenses/NOTICE; do
+            grep -q "$f" "$RUNNER_TEMP/wheel.txt" || { echo "missing from the wheel: $f"; exit 1; }
+          done
+      - name: Install the wheel into a clean venv
+        run: |
+          python -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/pip" install --upgrade pip
+          "$RUNNER_TEMP/venv/bin/pip" install dist/*.whl
+      - name: Run the installed command
+        working-directory: ${{ runner.temp }}     # away from the checkout's src/ and config/
+        shell: bash
+        run: |
+          export PATH="$RUNNER_TEMP/venv/bin:$PATH" FOURIER_HOME="$RUNNER_TEMP/home"
+          fourier --version
+          python -m fourier --help
+          fourier devices list
+          # no library and no database here, so doctor reports FAILs and exits non-zero:
+          # it only has to run to the end
+          fourier doctor > doctor.txt 2>&1 || true
+          cat doctor.txt
+          if grep -q Traceback doctor.txt; then exit 1; fi
+          fourier demo --dir "$RUNNER_TEMP/demo"

fourier_samples-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Release
+
+# A version tag (v0.1.0) builds the package and publishes it to PyPI with Trusted Publishing:
+# no token is stored anywhere. PyPI trusts this workflow once the project's trusted publisher
+# names it (github.com/bvk7787/fourier-samples, workflow release.yml, environment pypi).
+# The tag must match the version in pyproject.toml. Nothing runs while the repository is private.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: The tag matches the version
+        if: startsWith(github.ref, 'refs/tags/')
+        shell: bash
+        run: |
+          want="v$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          [ "$GITHUB_REF_NAME" = "$want" ] || { echo "tag $GITHUB_REF_NAME, pyproject says $want"; exit 1; }
+      - name: Build the sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check --strict dist/*
+      - name: The wheel installs and runs
+        shell: bash
+        run: |
+          python -m venv "$RUNNER_TEMP/v"
+          "$RUNNER_TEMP/v/bin/pip" install dist/*.whl
+          "$RUNNER_TEMP/v/bin/fourier" --version
+          "$RUNNER_TEMP/v/bin/fourier" demo --dir "$RUNNER_TEMP/demo"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: ${{ !github.event.repository.private && startsWith(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fourier-samples/
+    permissions:
+      id-token: write            # Trusted Publishing: PyPI checks this workflow's identity
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

fourier_samples-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.python-version
+.DS_Store
+# device manual PDFs kept beside the checkout (makers' copyright; never committed)
+docs/manuals/
+# a local configuration
+fourier.toml
+# local overrides
+/local/
+/CLAUDE.local.md

fourier_samples-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+# Instructions for coding agents
+
+Helping someone *use* Fourier Samples (their library, a build, a device)? Read
+[skills/fourier/SKILL.md](skills/fourier/SKILL.md). Changing its code? Read on.
+
+- Read [CLAUDE.md](CLAUDE.md) first: the ground rules (the library's files are never changed,
+  device facts come from the manuals, no one's library in the code), the architecture, and the
+  checks to run before a change is done.
+- Adding or changing a device profile: [docs/device-profiles.md](docs/device-profiles.md).
+- Contributing (tests, the CLI snapshot, what a pull request needs):
+  [CONTRIBUTING.md](CONTRIBUTING.md).
+- Ratings don't need Ableton Live: `fourier review rate` and `fourier review import` write the
+  same store Live's tag harvest writes (packs/ratings.py).

fourier_samples-0.1.0/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to Fourier Samples are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) (before 1.0, a minor version may
+change the CLI or the config).
+
+## [0.1.0] - 2026-10-04
+
+The first public release.
+
+### Added
+
+- **The command line, for people new to it.** `fourier --help` lists seventeen commands in
+  sections (Get started, Build and load, Releases, Look inside, Settings, Listen and rate,
+  Advanced). `fourier setup` is a step-by-step wizard (or `--yes` with flags): the sample
+  folders (counted, with a warning for cloud-only files), devices and style ("What do you
+  make?"), output folders, the config file, the CLAP model (it installs PyTorch and
+  Transformers into the running environment with uv or pip, the CPU-only PyTorch on Linux
+  without an NVIDIA GPU, and downloads the pinned model), an optional local LLM through Ollama,
+  then doctor's checks and the first build. `fourier build` (every category; or one) scans the
+  library and analyzes what's new before it builds (`--no-scan` skips both), with stage headers
+  and an estimate up front; on a terminal its Build and Verify stages show progress and a
+  summary (what it built, what it left empty, verify's result), with everything else in a log
+  in `<home>/logs` (`--verbose` prints it all). The steps underneath are `fourier tools` (`scan`, `analyze`,
+  `train`, `audit`, `import-folder`, `dedup`, `resolve`, `db-stats`); `publish --dry-run` and
+  `render --dry-run` preview what a release or a render would change.
+- **Curation.** `fourier build` turns a sample library into one master of
+  `CATEGORY/family/file.wav` folders: nineteen categories in play order (an overlay can add
+  more), families clustered from CLAP embeddings and named for what they sound like, drum kits
+  (`KITS`) and slice-ready loops (`SLICE`), and a manifest recording where every file came from
+  and why it's there. Builds are deterministic and stable (a rule change moves only the files
+  it touches), resumable (`--resume`), and swapped into place only when every category built
+  and verify passed. A category the library has too few samples for is left empty and named,
+  not a failure.
+- **The master's size follows the library** (`scale = "library"`): a style's budgets are for a
+  large library, and a smaller one gets a master in proportion. `fourier doctor`, setup and
+  `build --dry-run` say how big it will be. `scale = "off"` and `files = N` keep fixed budgets;
+  `size` caps them to fit a device.
+- **Export DSP.** DC offset, phase-flipped stereo, clicks at the end, hot starts, long tails,
+  per-folder loudness, and notes a few cents off are fixed on the way into the master.
+- **Any library layout, with or without other apps.** A build's scan reads Sononym's analysis
+  and Ableton Live's auto-tags when they're there, and otherwise walks the library folders.
+  Neither app is needed: built-in `path` and `audio` classifiers (folder and file names, WAV
+  chunks, and the audio itself) stand in, with your own words (`words`), and `vendors = "auto"`
+  reads each folder as vendor/pack folders, folders by sound type, an umbrella of packs or a
+  flat folder. Files no name rule recognizes are placed by sound: by CLAP's prompts, and by a
+  sound model trained on your own library (below). Fourier's own analysis (librosa features,
+  CLAP embeddings, sample-chain events, loop trims, pYIN roots and keys) runs with or without
+  Sononym and is stored apart from Sononym's; a resolver records which source each value a
+  build uses came from. The library's own files are never changed.
+- **A sound model trained on your library** (without Sononym). The first build trains a small
+  classifier over each sample's CLAP embedding and Fourier's own measurements, taught by how
+  your sample makers named their files and folders and by your ratings (never by Sononym's or
+  Live's analysis), once the names label enough samples; it retrains when the library has grown
+  a lot, and keeps it only when it's reliable on the packs it didn't learn from; `fourier tools
+  train` trains it any time. It places what no name rule recognizes when it's confident, and
+  its weights and report stay in your Fourier home. Fourier ships no
+  weights: they'd be learned from licensed samples. `fourier setup --no-sound-model` turns it
+  off.
+- **Cloud-synced libraries.** `fourier setup` and `fourier doctor` count the files a cloud
+  drive keeps only online, the analysis skips them (`fourier tools analyze --download` fetches
+  them first), and a build downloads the ones it picks before reading any and stops, writing
+  nothing, if one won't download.
+- **A second library** can share the Fourier home: another config (`fourier setup --to
+  other.toml`) gets its own master, renders and releases.
+- **Checks and explanations.** `fourier verify` checks the master against every curation rule
+  (and, with `--render`, scratch device renders); `fourier why` says where a sample landed and
+  which rule put it there, or why it was left out, and `why --unrecognized` lists what no rule
+  recognized; `fourier diff` compares two builds.
+- **Releases and devices.** `fourier publish` cuts immutable releases; `fourier render` converts
+  the master or a release for a device; a released render locks its paths on that device, so
+  later releases never move them. `fourier sync` copies a render onto an SD card without
+  macOS's `._` files.
+- **Device profiles** for the Elektron Digitakt 2 and the Dirtywave M8, every value citing a
+  page of the device's manual or marked as a convention or unverified, plus `generic_44k`,
+  `generic_48k`, `generic_folder` and `generic_sd_card`. `fourier devices new` writes a profile
+  for your own device; `fourier devices list|show`.
+- **Configuration.** Style presets (`balanced`, the default and the code's own settings,
+  `breaks-acid`, which the other genre styles build on, `hiphop-lofi`, `house-techno`,
+  `ambient-cinematic`, `trap`), fifteen knobs (`devices`, `categories`, `tempo`,
+  `fold`, `scale`, `files`, `size`, `loudness`, `retune`, `stereo`, `names`, `vendors`, `words`,
+  `sets`, `sources`), overlays and `--set KEY=VALUE` layer over the code's defaults; `fourier
+  config show|explain` prints what resolved and from where. `fourier doctor` checks what a
+  build needs, fails on anything that would stop one, and estimates how long it takes.
+- **The listening loop.** Rate the master's files Keep, Drop or Misfiled with `fourier review
+  rate` or `review import` (a CSV file), or with tags in Ableton Live's browser; `fourier
+  review` scores a build against the ratings and queues the files whose rating teaches the
+  most. Every build follows the ratings.
+- **Search.** `fourier search` by words or a reference file (CLAP), or by duration, tempo and
+  descriptors.
+- **`fourier demo`**: the whole pipeline on a generated library, in a sandbox folder with its own
+  home and config, with no samples, model or download needed.
+- **Safety guards.** Commands that write or delete refuse a library folder, a release, the
+  home folder, a volume root and any folder they didn't make: a build stops on a master holding
+  files it didn't make and lists them, renders and the demo replace only folders they marked as
+  theirs, and `fourier sync --delete` removes only what it copied to that card. A first run's
+  usual errors are one line saying what to run, not a traceback.
+- **Preparer plug-ins** (`fourier.preparers` entry points) for open formats soundfile doesn't
+  read.
+- **For people new to Terminal**: a step-by-step getting-started page for the Mac
+  (`docs/start.md`); setup takes a folder dragged in from Finder, devices and styles by number
+  or name, and asks how big a set (starter, standard, full, with load times for Transfer),
+  prepared for hardware or as-is, and which kinds of sound to leave out; `fourier open` shows the
+  master, a render, the releases or the logs in your file browser; `fourier config edit` opens
+  fourier.toml in a text editor (and runs with a config that doesn't load, which is when it's
+  needed); a fourier.toml typed with smart quotes still loads, and a mistake in one names its
+  line and the usual fix. `fourier config explain <setting>` says what a setting does in plain
+  words, with an example.
+- **A report page**: `fourier open report` opens a page in the web browser with every category
+  and family, a play button for each file, where it came from, what the build left out and why,
+  and Keep / Drop / Misfiled buttons that export a CSV for `fourier review import`.
+- **Plain answers**: `fourier why` answers in one sentence (`--detail` for every rule, vote and
+  score); a command that hits something unexpected says so in one line and keeps the details in
+  a file for a bug report; commands with nothing built yet say what to run first.
+- **Loading only what's new**: `fourier render <device> --release v2 --new-only` also copies the
+  files v2 adds into a folder of their own, for a loader that can't sync (Elektron Transfer).
+- **Documentation**: the README, a guide to what comes after the first build
+  (`docs/guide.md`), the reference (`docs/usage.md`), the curation rules (`docs/curation.md`),
+  and a skill for coding assistants (`skills/fourier/SKILL.md`) that teaches one to help with
+  Fourier safely.
+- `fourier --version`, and `python -m fourier`.
+- Python 3.11 to 3.13 on macOS and Linux; Windows is experimental.
+
+[0.1.0]: https://github.com/bvk7787/fourier-samples/releases/tag/v0.1.0