x32scene 0.1.0__tar.gz

x32scene-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Farr
+
+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.

x32scene-0.1.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: x32scene
+Version: 0.1.0
+Summary: Read, diff, edit and verify Behringer X32 / M32 console files (scenes, snippets, presets, shows) and read the live desk over OSC
+Author: Mike Farr
+License-Expression: MIT
+Project-URL: Repository, https://github.com/phierceweb/x32scene
+Project-URL: Changelog, https://github.com/phierceweb/x32scene/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/phierceweb/x32scene/issues
+Keywords: x32,m32,behringer,osc,audio,mixing-console,live-sound,scene-files,snippets
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pf-core~=0.22.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# x32scene
+
+[![PyPI](https://img.shields.io/pypi/v/x32scene)](https://pypi.org/project/x32scene/)
+
+Create X32 / M32 console files on the fly. Build, update, modify, transfer settings using AI via Python.
+
+# Why x32scene
+
+The X32 is a wildly capable mixer. Almost anything can be routed anywhere between hardware
+inputs and outputs. With that capability comes a lot of complexity and a steep learning
+curve, and developing a great scene is a lot of work: the right EQs, frequency-keyed gate
+settings, the aux setup for each player's in-ears, the routing to the stage boxes. Copying
+any of it by hand, one control at a time, is slow and easy to get wrong. **x32scene**
+exposes commands that do that work on the scene file and save a new scene that loads
+onto the desk.
+
+Some of the things it does that are hard to do any other way:
+
+- **Move a whole set of inputs to a second stage box.** Each channel's source is re-pointed
+  through the routing banks and its head-amp gain and phantom travel with it, because
+  the X32 stores gain by physical input, not by channel; the move is all-or-nothing, with
+  every target input range-checked first.
+- **Carry one player's in-ear mix into the next band's scene.** A monitor mix is a bus
+  strip plus every sender's send into it, both sides of a stereo pair; `transplant` moves
+  exactly those lines and nothing else, and `snippet --bus` writes the same mix as a
+  snippet the desk recalls mid-changeover while every other aux stays put. Loaded on a
+  console, a full pull afterwards differed from the starting scene in only that pair's
+  lines.
+- **Set an effect by parameter name.** Every one of the 61 effect types is mapped
+  parameter by parameter, so "plate in FX 4, decay 2.1, damping 8 kHz" is one command,
+  written in the desk's own token format; a type change starts from the parameter line
+  the desk itself writes.
+- **Describe a whole night in one file.** A JSON plan — names, head amps, EQ, dynamics,
+  monitor mixes, effects, routing, outputs — applied to a known-good template, every
+  value checked against the console's vocabulary, and the result refused if it changed
+  anything the plan did not name.
+- **Know what actually changed.** `diff --by-strip` says "channel 23, send to bus 9,
+  level −14.0 → −11.0", and `history` follows one parameter across every scene you have
+  saved.
+
+## What it is
+
+An X32 stores its state as plain text, one parameter per line: input patching, head amps,
+every monitor mix, effects, routing. The console and its editor edit that state one
+control at a time. x32scene works on the files instead. It parses every kind the console
+reads and writes, keeps each file byte for byte (`Scene.parse(text).dump() == text`), and
+applies edits so that the result differs from its source by exactly the intended lines —
+which `x32scene diff` shows. Edit commands never overwrite the file they read; the
+changed file is loaded on the console by you.
+
+The live layer is read-only: `pull` captures the running desk as a scene file so every
+command works on the live console, `desk` reports its identity, status and memory slots,
+`meters` reports levels. Pushing changes to the desk over the network is not a feature.
+
+Every command has a `--json` form, the vocabularies the console accepts are listed by
+commands, and the reference docs state which facts were observed on hardware and which
+were read from a manual, so the tool can be driven by an AI agent as well as by hand.
+
+## What it handles
+
+| File | What it is | Read | Write |
+|---|---|---|---|
+| `.scn` | a whole console | yes | every edit command, `band-setup`, `transplant` |
+| `.snp` | a snippet — lines the desk recalls *in place*, everything else untouched | yes | `snippet` |
+| `.chn` | one channel strip, per section | yes | `extract-preset` / `apply-preset` |
+| `.efx` | one effect slot | yes | `extract-fx` / `apply-fx` |
+| `.rou` | the input routing banks | yes | `extract-routing` / `apply-routing` |
+| `.shw` | a show: cues that recall scenes and snippets | yes | `show-build` |
+
+[docs/capabilities.md](https://github.com/phierceweb/x32scene/blob/main/docs/capabilities.md)
+lists every command by the job it does.
+
+## What the operations are
+
+**Reading.** Channel sources resolved through the routing banks and user patch, every
+output's feed and tap point, the mix buses and their stereo pairs, one monitor mix or all
+of them as a matrix, the USB record map, the FX rack with parameters by name, DCA and
+mute groups, the desk-wide settings (monitor, talkback, oscillator, recorder, user-assign
+buttons) in words, and a markdown report of the whole scene.
+
+**Comparing.** `diff` between two files, by path or grouped by strip with the moved
+fields named; `history` of one parameter across a dated library; `audit` of a library's
+structural invariants; `live-diff` of the desk against a file.
+
+**Editing.** Strip settings (name, fader, mute, pan, EQ, low cut, compressor, gate), FX
+slots by parameter name, a channel's input source, an output's feed, the routing banks.
+Values are written in the console's own token formats, checked against its vocabularies,
+and mirrored to a stereo-linked partner unless told not to.
+
+**Carrying between scenes.** `transplant` copies chosen lines from one scene into another
+and touches nothing else: a whole monitor mix (the bus strip and every send into it), any
+path pattern, or a channel's sections with the head amp re-mapped. Presets do the same
+one strip, slot or bank at a time.
+
+**Snippets.** The delta between two scenes, edits applied in memory, or one monitor mix
+whole, written with the filter masks the desk reads derived from the body. Loaded on a
+console, a snippet of one bus pair changed that pair's lines and no others; the details are
+in the console-behaviour doc.
+
+**Plans and shows.** `band-setup` applies one JSON plan (names, head amps, processing,
+monitor mixes, effects, routing, outputs) to a template, validates every value first, and
+refuses to write if the result strays outside the paths the plan named. `show-build`
+writes a show index with cues and its companion files in the shape X32-Edit imports.
+
+**Checks.** `preflight` compares a scene against a documented rig — outputs, monitor
+skeleton, routing, stereo links, send taps, groups — and a stage sidecar recording which
+jack and which person each output feeds. Exit 1 on a failure.
+
+## What the desk does with a file
+
+A file that round-trips and diffs clean can still not do what was intended once the
+console loads it. The docs record what was learned by loading files on hardware and
+reading the state back: the token formats a bad value silently aborts a line on, the
+frequencies and effect parameters the desk snaps to its own grid, how stereo-linked pairs
+reconcile on recall, and the difference between the desk's USB import and X32-Edit's Load
+(which pushes a file's lines from the computer). See
+[docs/console-behavior.md](https://github.com/phierceweb/x32scene/blob/main/docs/console-behavior.md)
+and its load-test loop before trusting a generated file at a gig.
+
+## Scope
+
+- Files and a read-only view of the desk. No network writes to the console.
+- Round-trip and diff prove a file is structurally correct and changed only where
+  intended; the console is the only proof it is semantically correct.
+- Snippets and presets loaded from a USB stick go through the desk's own recall and
+  header masks; X32-Edit's Load pushes the lines instead. Both were used in testing; the
+  USB route was not observed directly.
+- Pre-1.0: pin to a tagged release.
+
+## How it relates to other tools
+
+| Tool | What it is | How x32scene relates |
+|---|---|---|
+| X32-Edit, Mixing Station | Editors for the live console | They change the desk one control at a time. x32scene works on the files those editors save and load, and shows what changed between two of them |
+| Patrick-Gilles Maillot's X32 utilities and protocol document | The reference for the console's OSC dialect, and command-line tools that copy, save and drive it | x32scene's OSC layer implements the read side of that dialect; its enumerations were checked against a console and the document's corrections are noted where the desk disagreed |
+| OSC libraries (python-osc and the like) | Generic OSC transport | x32scene carries its own small X32 dialect encoder, because the console's node queries and meter blobs are not plain OSC |
+| A scene library in git | Version control of `.scn` files | x32scene adds a diff in the console's terms and edits that keep every other byte in place |
+
+## Install
+
+```bash
+pip install x32scene
+```
+
+Python 3.12 or newer, one dependency ([pf-core](https://pypi.org/project/pf-core/)).
+Releases are tagged; `main` is the development line. Release notes:
+[CHANGELOG.md](https://github.com/phierceweb/x32scene/blob/main/CHANGELOG.md).
+
+## Commands
+
+```bash
+x32scene info | inputs | ports | buses | iem | iem-matrix | record-map | fx | dca | console | report   scene.scn
+x32scene header FILE                       # any file's header decoded
+x32scene show show.shw                     # a show index
+x32scene diff a.scn b.scn [--by-strip]     # what changed
+x32scene history PATH… --dir DIR           # one parameter across a library
+x32scene set-eq | set-comp | set-gate | set-lowcut | set-fader | set-mute | set-pan | rename   scene.scn STRIP … -o out.scn
+x32scene set-fx | set-input | set-output | set-routing   scene.scn … -o out.scn
+x32scene transplant src.scn dst.scn -o out.scn --bus 1 --path /headamp/000 --ch 3 --scope eq
+x32scene snippet a.scn b.scn -o delta.snp | a.scn -o mix.snp --bus 9 | a.scn -o eq.snp --edit "set-eq 5 2 --gain 3"
+x32scene band-setup template.scn plan.json -o out.scn [--snippet out.snp]
+x32scene show-build -o DIR --name Night --scene a.scn --snippet x.snp --cue "1 Opener scene=0"
+x32scene preflight scene.scn --config rig.json [--stage stage.json]
+x32scene pull reference.scn -o live.scn | live-diff scene.scn | desk | meters   # --ip or X32SCENE_IP
+```
+
+Every command, flag and environment variable:
+[docs/cli.md](https://github.com/phierceweb/x32scene/blob/main/docs/cli.md). Example
+inputs: [`config/example-preflight.json`](https://github.com/phierceweb/x32scene/blob/main/config/example-preflight.json),
+[`config/example-plan.json`](https://github.com/phierceweb/x32scene/blob/main/config/example-plan.json),
+[`config/example-stage.json`](https://github.com/phierceweb/x32scene/blob/main/config/example-stage.json).
+
+## Use it from Python
+
+```python
+from x32scene import Scene
+from x32scene.services import transforms as T, transplant
+
+sc = Scene.load("scene.scn")
+T.rename_channel(sc, 1, "Kick In")
+T.set_headamp(sc, "local", 1, gain_db=30.0, phantom=False)
+sc.save("out.scn")
+
+other = Scene.load("friday.scn")
+transplant.transplant(sc, other, buses=[9])      # this scene's bus-9 mix into the other
+```
+
+The band-setup workflow is one call and raises rather than write anything outside the plan:
+
+```python
+from x32scene.orchestrators.band_swap import load_plan, run
+
+report = run("template.scn", load_plan("plan.json"), "out.scn")
+```
+
+## Working from a checkout
+
+```bash
+git clone https://github.com/phierceweb/x32scene && cd x32scene
+bin/run setup          # venv, editable install
+bin/run pytest         # the suite
+bin/run lint           # ruff + the pf-core structural gate
+bin/run x32scene …     # the CLI, with .env loaded
+```
+
+`X32SCENE_CORPUS=~/path/to/scenes bin/run pytest tests/test_roundtrip.py` runs the
+round-trip test over your own library.
+
+## Docs
+
+[docs/README.md](https://github.com/phierceweb/x32scene/blob/main/docs/README.md) is the
+index, maintained beside the docs.
+
+- [capabilities.md](https://github.com/phierceweb/x32scene/blob/main/docs/capabilities.md) — everything x32scene does, by job, and what it deliberately does not do
+- [cli.md](https://github.com/phierceweb/x32scene/blob/main/docs/cli.md) — every command, flag and environment variable
+- [format.md](https://github.com/phierceweb/x32scene/blob/main/docs/format.md) — every file kind and every line, field by field; the enumerations; what is verified against hardware and what is inferred
+- [console-behavior.md](https://github.com/phierceweb/x32scene/blob/main/docs/console-behavior.md) — what the desk does when it loads a file, and how a file reaches the desk
+- [routing.md](https://github.com/phierceweb/x32scene/blob/main/docs/routing.md) — the two-layer routing model, resolving a channel to its jack, the record map
+- [stage-sidecar.md](https://github.com/phierceweb/x32scene/blob/main/docs/stage-sidecar.md) — recording which jack and which person each output feeds, and what `preflight` checks against it
+
+## Built on pf-core
+
+x32scene is built on [pf-core](https://github.com/phierceweb/pf-core)
+([PyPI](https://pypi.org/project/pf-core/)), a Python foundation for LLM-facing
+applications. x32scene uses its atomic-write utilities, structured logging, exception
+boundary and config-from-env, and its structural gate, which fails the build when a file
+outgrows its line budget.
+
+For other phierceweb projects, see [github.com/phierceweb](https://github.com/phierceweb).
+
+## Contributing
+
+[CONTRIBUTING.md](https://github.com/phierceweb/x32scene/blob/main/CONTRIBUTING.md): never
+break the round-trip, run `bin/run lint` and the suite, and a real scene file that does not
+round-trip is the most useful bug report — with the console model and firmware, not the file.
+
+## Security
+
+[SECURITY.md](https://github.com/phierceweb/x32scene/blob/main/SECURITY.md). x32scene
+sends nothing off the local network, stores no credentials, and its live layer only reads
+the desk.
+
+## License
+
+MIT — see [LICENSE](https://github.com/phierceweb/x32scene/blob/main/LICENSE).
+
+Not affiliated with, endorsed by, or sponsored by Music Tribe. BEHRINGER, X32, and M32 are
+trademarks of Music Tribe Global Brands Ltd. See
+[TRADEMARKS.md](https://github.com/phierceweb/x32scene/blob/main/TRADEMARKS.md).

x32scene-0.1.0/README.md

@@ -0,0 +1,249 @@
+# x32scene
+
+[![PyPI](https://img.shields.io/pypi/v/x32scene)](https://pypi.org/project/x32scene/)
+
+Create X32 / M32 console files on the fly. Build, update, modify, transfer settings using AI via Python.
+
+# Why x32scene
+
+The X32 is a wildly capable mixer. Almost anything can be routed anywhere between hardware
+inputs and outputs. With that capability comes a lot of complexity and a steep learning
+curve, and developing a great scene is a lot of work: the right EQs, frequency-keyed gate
+settings, the aux setup for each player's in-ears, the routing to the stage boxes. Copying
+any of it by hand, one control at a time, is slow and easy to get wrong. **x32scene**
+exposes commands that do that work on the scene file and save a new scene that loads
+onto the desk.
+
+Some of the things it does that are hard to do any other way:
+
+- **Move a whole set of inputs to a second stage box.** Each channel's source is re-pointed
+  through the routing banks and its head-amp gain and phantom travel with it, because
+  the X32 stores gain by physical input, not by channel; the move is all-or-nothing, with
+  every target input range-checked first.
+- **Carry one player's in-ear mix into the next band's scene.** A monitor mix is a bus
+  strip plus every sender's send into it, both sides of a stereo pair; `transplant` moves
+  exactly those lines and nothing else, and `snippet --bus` writes the same mix as a
+  snippet the desk recalls mid-changeover while every other aux stays put. Loaded on a
+  console, a full pull afterwards differed from the starting scene in only that pair's
+  lines.
+- **Set an effect by parameter name.** Every one of the 61 effect types is mapped
+  parameter by parameter, so "plate in FX 4, decay 2.1, damping 8 kHz" is one command,
+  written in the desk's own token format; a type change starts from the parameter line
+  the desk itself writes.
+- **Describe a whole night in one file.** A JSON plan — names, head amps, EQ, dynamics,
+  monitor mixes, effects, routing, outputs — applied to a known-good template, every
+  value checked against the console's vocabulary, and the result refused if it changed
+  anything the plan did not name.
+- **Know what actually changed.** `diff --by-strip` says "channel 23, send to bus 9,
+  level −14.0 → −11.0", and `history` follows one parameter across every scene you have
+  saved.
+
+## What it is
+
+An X32 stores its state as plain text, one parameter per line: input patching, head amps,
+every monitor mix, effects, routing. The console and its editor edit that state one
+control at a time. x32scene works on the files instead. It parses every kind the console
+reads and writes, keeps each file byte for byte (`Scene.parse(text).dump() == text`), and
+applies edits so that the result differs from its source by exactly the intended lines —
+which `x32scene diff` shows. Edit commands never overwrite the file they read; the
+changed file is loaded on the console by you.
+
+The live layer is read-only: `pull` captures the running desk as a scene file so every
+command works on the live console, `desk` reports its identity, status and memory slots,
+`meters` reports levels. Pushing changes to the desk over the network is not a feature.
+
+Every command has a `--json` form, the vocabularies the console accepts are listed by
+commands, and the reference docs state which facts were observed on hardware and which
+were read from a manual, so the tool can be driven by an AI agent as well as by hand.
+
+## What it handles
+
+| File | What it is | Read | Write |
+|---|---|---|---|
+| `.scn` | a whole console | yes | every edit command, `band-setup`, `transplant` |
+| `.snp` | a snippet — lines the desk recalls *in place*, everything else untouched | yes | `snippet` |
+| `.chn` | one channel strip, per section | yes | `extract-preset` / `apply-preset` |
+| `.efx` | one effect slot | yes | `extract-fx` / `apply-fx` |
+| `.rou` | the input routing banks | yes | `extract-routing` / `apply-routing` |
+| `.shw` | a show: cues that recall scenes and snippets | yes | `show-build` |
+
+[docs/capabilities.md](https://github.com/phierceweb/x32scene/blob/main/docs/capabilities.md)
+lists every command by the job it does.
+
+## What the operations are
+
+**Reading.** Channel sources resolved through the routing banks and user patch, every
+output's feed and tap point, the mix buses and their stereo pairs, one monitor mix or all
+of them as a matrix, the USB record map, the FX rack with parameters by name, DCA and
+mute groups, the desk-wide settings (monitor, talkback, oscillator, recorder, user-assign
+buttons) in words, and a markdown report of the whole scene.
+
+**Comparing.** `diff` between two files, by path or grouped by strip with the moved
+fields named; `history` of one parameter across a dated library; `audit` of a library's
+structural invariants; `live-diff` of the desk against a file.
+
+**Editing.** Strip settings (name, fader, mute, pan, EQ, low cut, compressor, gate), FX
+slots by parameter name, a channel's input source, an output's feed, the routing banks.
+Values are written in the console's own token formats, checked against its vocabularies,
+and mirrored to a stereo-linked partner unless told not to.
+
+**Carrying between scenes.** `transplant` copies chosen lines from one scene into another
+and touches nothing else: a whole monitor mix (the bus strip and every send into it), any
+path pattern, or a channel's sections with the head amp re-mapped. Presets do the same
+one strip, slot or bank at a time.
+
+**Snippets.** The delta between two scenes, edits applied in memory, or one monitor mix
+whole, written with the filter masks the desk reads derived from the body. Loaded on a
+console, a snippet of one bus pair changed that pair's lines and no others; the details are
+in the console-behaviour doc.
+
+**Plans and shows.** `band-setup` applies one JSON plan (names, head amps, processing,
+monitor mixes, effects, routing, outputs) to a template, validates every value first, and
+refuses to write if the result strays outside the paths the plan named. `show-build`
+writes a show index with cues and its companion files in the shape X32-Edit imports.
+
+**Checks.** `preflight` compares a scene against a documented rig — outputs, monitor
+skeleton, routing, stereo links, send taps, groups — and a stage sidecar recording which
+jack and which person each output feeds. Exit 1 on a failure.
+
+## What the desk does with a file
+
+A file that round-trips and diffs clean can still not do what was intended once the
+console loads it. The docs record what was learned by loading files on hardware and
+reading the state back: the token formats a bad value silently aborts a line on, the
+frequencies and effect parameters the desk snaps to its own grid, how stereo-linked pairs
+reconcile on recall, and the difference between the desk's USB import and X32-Edit's Load
+(which pushes a file's lines from the computer). See
+[docs/console-behavior.md](https://github.com/phierceweb/x32scene/blob/main/docs/console-behavior.md)
+and its load-test loop before trusting a generated file at a gig.
+
+## Scope
+
+- Files and a read-only view of the desk. No network writes to the console.
+- Round-trip and diff prove a file is structurally correct and changed only where
+  intended; the console is the only proof it is semantically correct.
+- Snippets and presets loaded from a USB stick go through the desk's own recall and
+  header masks; X32-Edit's Load pushes the lines instead. Both were used in testing; the
+  USB route was not observed directly.
+- Pre-1.0: pin to a tagged release.
+
+## How it relates to other tools
+
+| Tool | What it is | How x32scene relates |
+|---|---|---|
+| X32-Edit, Mixing Station | Editors for the live console | They change the desk one control at a time. x32scene works on the files those editors save and load, and shows what changed between two of them |
+| Patrick-Gilles Maillot's X32 utilities and protocol document | The reference for the console's OSC dialect, and command-line tools that copy, save and drive it | x32scene's OSC layer implements the read side of that dialect; its enumerations were checked against a console and the document's corrections are noted where the desk disagreed |
+| OSC libraries (python-osc and the like) | Generic OSC transport | x32scene carries its own small X32 dialect encoder, because the console's node queries and meter blobs are not plain OSC |
+| A scene library in git | Version control of `.scn` files | x32scene adds a diff in the console's terms and edits that keep every other byte in place |
+
+## Install
+
+```bash
+pip install x32scene
+```
+
+Python 3.12 or newer, one dependency ([pf-core](https://pypi.org/project/pf-core/)).
+Releases are tagged; `main` is the development line. Release notes:
+[CHANGELOG.md](https://github.com/phierceweb/x32scene/blob/main/CHANGELOG.md).
+
+## Commands
+
+```bash
+x32scene info | inputs | ports | buses | iem | iem-matrix | record-map | fx | dca | console | report   scene.scn
+x32scene header FILE                       # any file's header decoded
+x32scene show show.shw                     # a show index
+x32scene diff a.scn b.scn [--by-strip]     # what changed
+x32scene history PATH… --dir DIR           # one parameter across a library
+x32scene set-eq | set-comp | set-gate | set-lowcut | set-fader | set-mute | set-pan | rename   scene.scn STRIP … -o out.scn
+x32scene set-fx | set-input | set-output | set-routing   scene.scn … -o out.scn
+x32scene transplant src.scn dst.scn -o out.scn --bus 1 --path /headamp/000 --ch 3 --scope eq
+x32scene snippet a.scn b.scn -o delta.snp | a.scn -o mix.snp --bus 9 | a.scn -o eq.snp --edit "set-eq 5 2 --gain 3"
+x32scene band-setup template.scn plan.json -o out.scn [--snippet out.snp]
+x32scene show-build -o DIR --name Night --scene a.scn --snippet x.snp --cue "1 Opener scene=0"
+x32scene preflight scene.scn --config rig.json [--stage stage.json]
+x32scene pull reference.scn -o live.scn | live-diff scene.scn | desk | meters   # --ip or X32SCENE_IP
+```
+
+Every command, flag and environment variable:
+[docs/cli.md](https://github.com/phierceweb/x32scene/blob/main/docs/cli.md). Example
+inputs: [`config/example-preflight.json`](https://github.com/phierceweb/x32scene/blob/main/config/example-preflight.json),
+[`config/example-plan.json`](https://github.com/phierceweb/x32scene/blob/main/config/example-plan.json),
+[`config/example-stage.json`](https://github.com/phierceweb/x32scene/blob/main/config/example-stage.json).
+
+## Use it from Python
+
+```python
+from x32scene import Scene
+from x32scene.services import transforms as T, transplant
+
+sc = Scene.load("scene.scn")
+T.rename_channel(sc, 1, "Kick In")
+T.set_headamp(sc, "local", 1, gain_db=30.0, phantom=False)
+sc.save("out.scn")
+
+other = Scene.load("friday.scn")
+transplant.transplant(sc, other, buses=[9])      # this scene's bus-9 mix into the other
+```
+
+The band-setup workflow is one call and raises rather than write anything outside the plan:
+
+```python
+from x32scene.orchestrators.band_swap import load_plan, run
+
+report = run("template.scn", load_plan("plan.json"), "out.scn")
+```
+
+## Working from a checkout
+
+```bash
+git clone https://github.com/phierceweb/x32scene && cd x32scene
+bin/run setup          # venv, editable install
+bin/run pytest         # the suite
+bin/run lint           # ruff + the pf-core structural gate
+bin/run x32scene …     # the CLI, with .env loaded
+```
+
+`X32SCENE_CORPUS=~/path/to/scenes bin/run pytest tests/test_roundtrip.py` runs the
+round-trip test over your own library.
+
+## Docs
+
+[docs/README.md](https://github.com/phierceweb/x32scene/blob/main/docs/README.md) is the
+index, maintained beside the docs.
+
+- [capabilities.md](https://github.com/phierceweb/x32scene/blob/main/docs/capabilities.md) — everything x32scene does, by job, and what it deliberately does not do
+- [cli.md](https://github.com/phierceweb/x32scene/blob/main/docs/cli.md) — every command, flag and environment variable
+- [format.md](https://github.com/phierceweb/x32scene/blob/main/docs/format.md) — every file kind and every line, field by field; the enumerations; what is verified against hardware and what is inferred
+- [console-behavior.md](https://github.com/phierceweb/x32scene/blob/main/docs/console-behavior.md) — what the desk does when it loads a file, and how a file reaches the desk
+- [routing.md](https://github.com/phierceweb/x32scene/blob/main/docs/routing.md) — the two-layer routing model, resolving a channel to its jack, the record map
+- [stage-sidecar.md](https://github.com/phierceweb/x32scene/blob/main/docs/stage-sidecar.md) — recording which jack and which person each output feeds, and what `preflight` checks against it
+
+## Built on pf-core
+
+x32scene is built on [pf-core](https://github.com/phierceweb/pf-core)
+([PyPI](https://pypi.org/project/pf-core/)), a Python foundation for LLM-facing
+applications. x32scene uses its atomic-write utilities, structured logging, exception
+boundary and config-from-env, and its structural gate, which fails the build when a file
+outgrows its line budget.
+
+For other phierceweb projects, see [github.com/phierceweb](https://github.com/phierceweb).
+
+## Contributing
+
+[CONTRIBUTING.md](https://github.com/phierceweb/x32scene/blob/main/CONTRIBUTING.md): never
+break the round-trip, run `bin/run lint` and the suite, and a real scene file that does not
+round-trip is the most useful bug report — with the console model and firmware, not the file.
+
+## Security
+
+[SECURITY.md](https://github.com/phierceweb/x32scene/blob/main/SECURITY.md). x32scene
+sends nothing off the local network, stores no credentials, and its live layer only reads
+the desk.
+
+## License
+
+MIT — see [LICENSE](https://github.com/phierceweb/x32scene/blob/main/LICENSE).
+
+Not affiliated with, endorsed by, or sponsored by Music Tribe. BEHRINGER, X32, and M32 are
+trademarks of Music Tribe Global Brands Ltd. See
+[TRADEMARKS.md](https://github.com/phierceweb/x32scene/blob/main/TRADEMARKS.md).

x32scene-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "x32scene"
+version = "0.1.0"
+description = "Read, diff, edit and verify Behringer X32 / M32 console files (scenes, snippets, presets, shows) and read the live desk over OSC"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mike Farr" }]
+keywords = ["x32", "m32", "behringer", "osc", "audio", "mixing-console", "live-sound", "scene-files", "snippets"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Typing :: Typed",
+]
+dependencies = ["pf-core~=0.22.0"]
+
+[project.urls]
+Repository = "https://github.com/phierceweb/x32scene"
+Changelog = "https://github.com/phierceweb/x32scene/blob/main/CHANGELOG.md"
+Issues = "https://github.com/phierceweb/x32scene/issues"
+
+[project.scripts]
+x32scene = "x32scene.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=5.0", "ruff>=0.6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+x32scene = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "B"]
+ignore = ["E501", "B008", "B904"]

x32scene-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

x32scene-0.1.0/src/x32scene/__init__.py

@@ -0,0 +1,16 @@
+"""Byte-faithful X32 / M32 scene-file toolkit."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .model import Line, Scene, tokenize
+from .services import (  # noqa: F401
+    audit, channelfx, diff, fx, groups, iem, presets, routing, scopes,
+    transforms,
+)
+
+try:
+    __version__ = version("x32scene")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["Line", "Scene", "tokenize", "__version__"]