Metadata-Version: 2.4
Name: audioatlas
Version: 0.2.0a8
Summary: A local single-track audio analysis framework for factual music maps.
Project-URL: Homepage, https://github.com/CharlesMish/AudioAtlas
Project-URL: Repository, https://github.com/CharlesMish/AudioAtlas
Project-URL: Issues, https://github.com/CharlesMish/AudioAtlas/issues
Project-URL: Live report, https://charlesmish.github.io/AudioAtlas/
Author: Charles Mish
License: MIT License
        
        Copyright (c) 2026 Charles Mish
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: analysis,audio,mastering,mixing,music,reports
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: filelock<4,>=3.16
Requires-Dist: librosa>=0.11
Requires-Dist: matplotlib>=3.8
Requires-Dist: msgpack>=1.2.1
Requires-Dist: numba<0.66,>=0.65.1
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=12.3.0
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: pyloudnorm>=0.1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.12
Requires-Dist: soundfile>=0.13
Provides-Extra: app-build
Requires-Dist: pyinstaller==6.21.0; extra == 'app-build'
Requires-Dist: pyobjc-core<13,>=11; extra == 'app-build'
Requires-Dist: pyobjc-framework-cocoa<13,>=11; extra == 'app-build'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: pip-audit<3,>=2.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: windows-app-build
Requires-Dist: pefile<2027,>=2024.8.26; extra == 'windows-app-build'
Requires-Dist: pip-licenses<6,>=5; extra == 'windows-app-build'
Requires-Dist: pyinstaller==6.21.0; extra == 'windows-app-build'
Description-Content-Type: text/markdown

# AudioAtlas

## See your track. Keep the judgment yours.

AudioAtlas turns one audio file into a private, portable listening map: key
measurements, clear plots, and a short list of places that may be worth checking
by ear.

It runs on your computer. There is no account, upload, server, telemetry, or
quality score. The result is a folder you can open in any browser and keep with
the track.

![AudioAtlas Midnight Studio report plots generated from the included demo](docs/assets/readme/midnight_report_plots.png)

AudioAtlas provides:

- local analysis with no intentional audio upload;
- portable HTML, Markdown, JSON, and PNG reports;
- Compact, Standard, and Full plot selections over the same complete analysis;
- bounded review prompts that describe measurements without grading the music.

## Quick start

Open the [live Midnight Studio report](https://charlesmish.github.io/AudioAtlas/)
to see the complete local-first experience before installing anything. It is
generated from the 70.98-second project demo track. The hosted sample contains
the static report only; AudioAtlas itself does not upload user audio or
generated reports.

The recommended `0.2.0a8` alpha installation is the Python package. AudioAtlas
supports Python 3.11 or newer on macOS, Windows, and Linux where its scientific
Python and audio-decoder dependencies are available.

```bash
python -m pip install audioatlas==0.2.0a8
audioatlas --version
audioatlas analyze song.wav --graphs-profile compact
```

When `--out` is omitted, the report appears in a folder such as
`audioatlas-report-song/` in the current directory. Open `report.html` inside
that folder. Use `--graphs-profile full` for all seventeen registered plots.

## Release status

### Python package and CLI

**Available — recommended installation for AudioAtlas 0.2.0a8 alpha.** The CLI
includes one-file reports, themes, graph profiles, batch reports, manual
sections, revision diffs, and song projects.

### macOS application

**Optional unsigned Apple Silicon technical preview — not signed or notarized.**
It requires Apple Silicon and macOS 14 or newer, is intended for experienced
testers, and is not the recommended installation route. Apple cannot
authenticate its developer or notarization status. Do not weaken or disable
macOS security controls to run it; use the Python package if normal launch is
blocked.

### Windows application

**Desktop download not included in this alpha — native Windows build and
acceptance remain pending.** Windows users can use the recommended Python CLI;
the native application is neither abandoned nor represented as ready.

## Source checkout

```bash
uv sync
uv run audioatlas analyze song.wav
```

The first analysis in a fresh environment may take a little longer while the
scientific libraries initialize. Lightweight commands such as `--version`,
`--help`, and `themes` start without loading the analysis stack.

## Try the real demo recordings

The repository includes three intentionally public musical demos: the complete
AudioAtlas trailer/demo track, a short solo-guitar recording, and a fuller
guitar, koto, cello, and drums arrangement.

```bash
# Reproduce the standard Midnight Studio report used by the live site
uv run audioatlas analyze examples/demo_audio/audioatlas_demo.wav \
  --out reports/audioatlas-demo \
  --graphs-profile standard \
  --theme midnight_studio

# Make a clean audio-only input folder, then build an exact three-track catalog
rm -rf reports/demo-audio-input
mkdir -p reports/demo-audio-input
cp examples/demo_audio/*.wav reports/demo-audio-input/
uv run audioatlas batch reports/demo-audio-input \
  --out reports/demo-catalog \
  --graphs-profile full

# Open the live-demo-style report, catalog, and arrangement report
python -m webbrowser reports/audioatlas-demo/report.html
python -m webbrowser reports/demo-catalog/catalog.html
python -m webbrowser reports/demo-catalog/guitar_koto_cello_drums/report.html
```

See the [recording notes](examples/demo_audio/README.md) and
[audio rights notice](AUDIO_RIGHTS.md). These musical demos are not golden test
fixtures or threshold-calibration evidence.

## Choose how much you want to see

AudioAtlas has one analysis engine. The choices below change report depth and
presentation, not the underlying measurements.

| Experience | Command | What changes |
|---|---|---|
| **Compact** | `--graphs-profile compact` | Four essential plots; complete JSON remains available |
| **Standard** | no extra flag | Fourteen plots and the normal first-read experience |
| **Full** | `--graphs-profile full` | All seventeen registered plots |

Every HTML report opens in **Studio** and includes a **Focus / Studio** switch:

- **Studio** is the polished default, with richer framing, hierarchy, and atmosphere.
- **Focus** is restrained and information-first.

Both views wrap the same report content and plot pixels. The presentation switch
changes framing only.

The polished light theme shown above is the no-flag default. Theme selection
styles both the report shell and generated PNG canvases at report-generation
time. Midnight Studio is an optional built-in alternative:

```bash
audioatlas analyze song.wav --theme midnight_studio
```

Choose the restrained opening view when generating a report:

```bash
audioatlas analyze song.wav --presentation focus
```

The switch remains available inside the finished report, works offline, and
never changes the measured plot content or pixels.

A separate “lite” build is intentionally not maintained. Compact reports use
the same trusted analysis engine, which avoids two editions slowly disagreeing
about the same track.

## Useful recipes

```bash
# Pick an output folder
audioatlas analyze song.wav --out reports/song

# Compact first read
audioatlas analyze song.wav --graphs-profile compact

# Restrained opening presentation
audioatlas analyze song.wav --presentation focus

# All plots with a built-in theme
audioatlas analyze song.wav --graphs-profile full --theme midnight_studio

# Analyze one source range
audioatlas analyze song.wav --start 30 --end 62 --out reports/verse

# List themes
audioatlas themes
```

## What you receive

A normal report folder contains:

- `report.html` — the friendly browser report;
- `report.md` — a portable text version;
- `summary.json` — the complete measurement summary;
- `findings.json` — bounded review prompts and their evidence;
- PNG plots;
- `.audioatlas-output.json` — a manifest that lets AudioAtlas update its own
  files without deleting unrelated files.

Local absolute paths are excluded by default, so shared reports do not normally
reveal usernames or folder structures.

The HTML report also provides keyboard-accessible plot zoom, direct links between
review prompts and their plots, and private Human notes. Notes autosave in local
browser storage for that report path and can be copied or exported as text; they
are never written into report JSON or sent over a network.

## Compare two revisions of the same track

Give related exports the same private revision token when you analyze them:

```bash
audioatlas analyze mix-v3.wav --out reports/mix-v3 --track-id "unique-private-token"
audioatlas analyze mix-v4.wav --out reports/mix-v4 --track-id "unique-private-token"
audioatlas diff reports/mix-v3 reports/mix-v4 --out reports/v3-to-v4
```

The diff reports descriptive `B - A` changes and which review prompts appeared,
disappeared, or changed. It does not choose a winner. AudioAtlas stores only the
token's SHA-256 digest; matching digests mean the same token was supplied, not
that AudioAtlas recognized the music.

## Keep a song's revisions together

For recurring work, create a private local song workspace and add each export
in order:

```bash
audioatlas project init projects/my-song --name "My Song"
audioatlas project add projects/my-song mix-v1.wav --label "Mix 1"
audioatlas project add projects/my-song mix-v2.wav --label "Mix 2"
```

Open `projects/my-song/project.html`. The workspace keeps per-revision reports
and guarded adjacent diffs together. Its YAML configuration records local
source paths for repeatable owner-side use, while generated JSON, Markdown, and
HTML expose only portable filenames and the hashed project identity.

## Analyze sections or a folder

Manual sections:

```bash
audioatlas sections song.wav --out reports/sections \
  --section intro:0:30 \
  --section verse:30:62 \
  --section ending:62:
```

Folder catalog:

```bash
audioatlas batch /path/to/audio --out reports/catalog
```

AudioAtlas does not infer song structure. Folder catalogs remain descriptive
and do not rank tracks.

## What AudioAtlas measures

AudioAtlas currently includes level and loudness context, approximate true
peak, clipping and near-clipping counts, RMS and crest timelines, short-term
LUFS, stereo correlation, mid/side energy, spectral shape, relative mean band
power, onset activity, and chroma pitch-class energy.

Review prompts are checks worth making, not diagnoses. A report may correctly
surface no prioritized prompts at all.

## What it does not do

- No mix, mastering, loudness, or quality score.
- No automatic EQ, compression, or mastering prescription.
- No cross-track ranking or reference-track winner.
- No genre, instrument, source, key, or automatic section detection.
- No source separation, cloud dashboard, playback engine, or DAW integration.
- No claim that a threshold crossing is audible, bad, or musically wrong.

## Alpha status

AudioAtlas `0.2.0a8` is a public alpha. The report pipeline, comparison tools,
and local song-project workflow are usable, but the default review prompts are
still being calibrated on real music. This release adds safer report
replacement, private source binding, GUI failure containment, and stricter
native packaging verification. Signed/notarized or Authenticode-signed desktop
artifacts plus clean-machine acceptance remain future gates; no desktop binary
is generally release-ready. The older `.command` and `.bat` launchers remain
convenience wrappers for an already installed CLI, not desktop installers.

Processing time and memory use vary with file length, format, graph profile,
and machine. Keep original audio and any reports you care about; alpha feedback
about installation clarity, report usefulness, and failures is welcome through
the project issue tracker. Reports are descriptive analysis tools, not
authoritative mastering judgments.

The temporary Numba compatibility range is documented in
[Compatibility](docs/COMPATIBILITY.md).

## Learn more

- [Friendly user guide](docs/USER_GUIDE.md)
- [Desktop app and legacy launchers](README_EASY_RUN.md)
- [Examples](examples/README.md)
- [Finding rules](docs/FINDING_RULES.md)
- [Alpha limitations](docs/ALPHA_LIMITATIONS.md)
- [Compatibility](docs/COMPATIBILITY.md)
- [Schemas](docs/SUMMARY_SCHEMA.md)
- [Song-project schema](docs/PROJECT_SCHEMA.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Changelog](docs/CHANGELOG.md)
- [Security policy](SECURITY.md)

## License

AudioAtlas software and software documentation use the [MIT License](LICENSE).
The published demo recordings have a separate [audio rights notice](AUDIO_RIGHTS.md),
including recording-specific CC BY 4.0 terms, an AI-assisted demo-only track,
and third-party sound exceptions.
