totalmix-osc 0.0.1__tar.gz

totalmix_osc-0.0.1/.github/workflows/ci.yaml

@@ -0,0 +1,32 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches:
+      - main
+    pull_request:
+      branches:
+        - main
+
+jobs:
+  tests:
+    name: Unit tests
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        os: ['ubuntu-latest', 'windows-latest', 'macos-latest']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+          pip install -e .[test]
+      - name: Test with pytest
+        run: |
+          pytest

totalmix_osc-0.0.1/.github/workflows/docs.yaml

@@ -0,0 +1,47 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs]
+      - name: Build documentation
+        run: mkdocs build --strict
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

totalmix_osc-0.0.1/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,38 @@
+name: Publish Python distribution to PyPI
+
+on:
+  push:
+    tags:
+      - '[0-9].[0-9]+.[0-9]+'
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python distribution to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/totalmix-osc
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@main
+      - name: Setup Python 3.10
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+      - name: Install pypa/build
+        run: >-
+          python -m 
+          pip install 
+          build 
+          --user
+      - name: Build a binary wheel and a source tarball
+        run: >-
+          python -m 
+          build 
+          --sdist
+          --wheel
+          --outdir dist/
+      - name: Publish distribution to PyPI
+        if: startsWith(github.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@release/v1

totalmix_osc-0.0.1/.gitignore

@@ -0,0 +1,77 @@
+totalmix_osc/version.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# MkDocs
+site/
+
+# PyBuilder
+target/
+
+
+# Vim global
+[._]*.s[a-w][a-z]
+[._]s[a-w][a-z]
+*.un~
+Session.vim
+.netrwhist
+*~
+
+
+__enamlcache__/
+sandbox/
+.ropeproject/
+.ipynb_checkpoints/

totalmix_osc-0.0.1/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+`totalmix-osc` controls RME TotalMix FX (the mixer software for RME audio
+interfaces) over its legacy OSC protocol: routing-matrix crosspoints,
+output gains, and output loopback, with every write verified against
+TotalMix's feedback. It was split out of `ncrar-audio` so psiexperiment can
+use it without depending on that package; `ncrar-audio` now depends on it.
+
+## Commands
+
+```bash
+pip install -e .[test,docs]
+pytest                              # offline, against tests/fake_totalmix.py
+pytest tests/test_control.py -k loopback
+pytest --hardware                   # also runs tests/test_hardware.py
+mkdocs build --strict
+```
+
+Versioning comes from git tags via `setuptools_scm`
+(`totalmix_osc/version.py` is generated). Pushing a tag like `0.1.0`
+publishes to PyPI via `.github/workflows/publish-to-pypi.yml`.
+
+## Architecture
+
+- `osc_client.py` (`OSCClient`): UDP send/receive. Uses a single-threaded
+  `BlockingOSCUDPServer` so feedback is handled in arrival order, and
+  converts every number to float before sending (TotalMix misreads OSC
+  ints).
+- `control.py` (`TotalMixFX`): reads the channel layout at construction
+  (walking banks with `/1/bank+`), then sends selector messages
+  (`/setSubmix`, `/setBankStart`, `/1/busX`, `/setOffsetInBank`) followed by
+  writes. `_on_feedback` records every relevant message with the context
+  (bus, submix label, page-2 channel) TotalMix last reported;
+  `_scan_fader`/`_scan_loopback` only trust a value once the same burst has
+  confirmed the expected channel name. `_transact` sends and waits on that
+  feedback.
+- `cli.py`: the `totalmix-osc` command (also `python -m totalmix_osc`).
+  Subcommands are get-or-set (omit the value to read); `shell` reuses one
+  `TotalMixFX` and parses each line with the same argparse subparsers.
+  Tested offline in `tests/test_cli.py`.
+- `fader_curve.py`: dB <-> raw fader value mapping from
+  `totalmix_fx_volume_map.json`.
+- `tests/fake_totalmix.py`: simulates the TotalMix behaviors the code
+  depends on (float misreads, banks, stale bursts, toggles, crashing on an
+  out-of-range selection). When you discover a new TotalMix behavior on
+  hardware, model it here and add a test.
+
+## Hardware cautions
+
+- Never send `/setBankStart` or `/setSubmix` past the end of a row: it can
+  crash TotalMix FX. Channel numbers are validated against the layout read
+  at startup; keep it that way.
+- The hardware tests change and restore the live mixer. Ask before running
+  them, and before sending any OSC writes to a real device.
+- `docs/guide.md` ("Legacy OSC protocol quirks") is the record of observed
+  protocol behavior; update it when you learn something new, and say
+  whether it was verified on hardware.

totalmix_osc-0.0.1/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: totalmix-osc
+Version: 0.0.1
+Summary: Verified control of RME TotalMix FX routing, gains, and loopback over OSC
+Author-email: "Buran Consulting, LLC" <info@bradburan.com>
+Maintainer-email: "Buran Consulting, LLC" <info@bradburan.com>
+License: Copyright 2026 totalmix-osc development team
+        
+        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: python-osc
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# totalmix-osc
+
+Verified control of RME TotalMix FX routing, gains, and loopback over OSC.
+
+```python
+from totalmix_osc import TotalMixFX
+
+with TotalMixFX() as tmfx:
+    tmfx.set_mono_straight_playback()   # Playback N -> Output N, nothing else
+    tmfx.set_gain(1, -6.0)
+    tmfx.set_loopback(9, True)
+```
+
+Every change is confirmed by TotalMix's own OSC feedback before returning,
+and a `TotalMixError` is raised if it isn't. Requires OSC Control and
+"Submix linked to OSC Control" to be enabled in TotalMix FX under
+Settings > OSC.
+
+A `totalmix-osc` command does the same from the command line, for
+checking changes by eye in the TotalMix window:
+
+```bash
+totalmix-osc gain "Phones L" -6
+totalmix-osc xp 2 playback 1 off
+totalmix-osc shell          # interactive, one connection
+```
+
+See the documentation for the full guide, including the quirks of
+TotalMix's legacy OSC protocol that this package works around.
+
+## Development
+
+```bash
+pip install -e .[test,docs]
+pytest                 # offline tests against a simulated TotalMix
+pytest --hardware      # also run against TotalMix FX and a connected device
+mkdocs serve
+```
+
+The hardware tests change the mixer's routing, gains, and loopback, then
+restore the original state.

totalmix_osc-0.0.1/docs/api.md

@@ -0,0 +1,9 @@
+# API reference
+
+::: totalmix_osc.TotalMixFX
+
+::: totalmix_osc.TotalMixError
+
+::: totalmix_osc.OSCClient
+
+::: totalmix_osc.load_volume_map

totalmix_osc-0.0.1/docs/guide.md

@@ -0,0 +1,300 @@
+# Guide
+
+`totalmix-osc` provides programmatic control of RME TotalMix FX -- the
+routing/mixing software behind RME audio interfaces such as the Fireface
+and Babyface -- via its OSC (Open Sound Control) interface. It exists to
+solve a specific problem: TotalMix's workspace can be changed by a stray
+click (wrong routing, wrong gain, a channel silently muted), which then
+breaks whatever experiment assumes a known-good mixer state. Rather than
+trusting a saved snapshot or settings file -- which is just as easy to
+overwrite by accident -- every function here fully reconstructs the state
+it touches from first principles, and verifies the result by waiting for
+TotalMix's own OSC feedback before returning.
+
+## Prerequisites
+
+This package targets TotalMix FX's legacy, stateful OSC protocol (not the
+"Global OSC" mode added in TotalMix FX 2.1). Two settings must be enabled
+once, by hand, in TotalMix FX under **Settings > OSC**:
+
+* **OSC Control** must be enabled.
+* **Submix linked to OSC Control** must be enabled. Without it,
+  `/setSubmix` -- which is used to address individual cells of the routing
+  matrix -- is silently ignored.
+
+Only one program can receive TotalMix's OSC feedback at a time, so close
+any other OSC tools (e.g., Bitfocus Companion) first.
+
+## Quickstart
+
+```python
+from totalmix_osc import TotalMixFX
+
+with TotalMixFX() as tmfx:
+    # Wipe out whatever routing/gain state TotalMix is currently in and
+    # reconstruct straight 1:1 mono playback from scratch: Playback channel
+    # N feeds Output channel N at unity gain, and nothing else (no other
+    # playback channel, no live hardware input) feeds that output.
+    tmfx.set_mono_straight_playback()
+
+    # Per-experiment gain, applied on top of the straight routing above.
+    tmfx.set_gain(channel=1, db=-6.0)
+    tmfx.set_gain(channel=2, db=-6.0)
+
+    # Return output 9's signal to the computer as a recording input.
+    tmfx.set_loopback(channel=9, enabled=True)
+```
+
+All channel numbers are 1-indexed, matching the TotalMix GUI.
+
+## Command line
+
+Installing the package adds a `totalmix-osc` command for checking and
+changing settings by hand, for example while watching the TotalMix window
+to confirm a change lands where you expect. Each command reads the
+current value if you leave the value off, and sets it otherwise. Changes
+are confirmed by TotalMix before the command returns. Channels can be
+given by number or by name.
+
+```text
+totalmix-osc layout                        # list channels in each row
+totalmix-osc gain 1                        # read Output 1's fader
+totalmix-osc gain "Phones L" -6            # set it to -6 dB
+totalmix-osc gain 9 off                    # fader fully down (-oo)
+totalmix-osc xp 2 playback 1 -12           # Playback 1 -> Output 2 at -12 dB
+totalmix-osc xp "Phones R" input "Analog 3" off
+totalmix-osc loopback 9 on
+totalmix-osc straight                      # straight 1:1 playback, all outputs
+totalmix-osc show 1 2                      # gain, loopback, and sources
+```
+
+Use `off` rather than `-inf` for silence; a value starting with `-` that
+isn't a number is read as an option.
+
+Starting the command reads the channel layout, which takes a second or
+two. To avoid repeating that, `totalmix-osc shell` keeps one connection
+open and accepts the same commands interactively (`help` lists them).
+Add `-v` to log progress, or `-vv` to log every OSC message sent. Run
+`totalmix-osc --help` for the connection options (`--ip`, ports,
+`--timeout`).
+
+## Channel layout
+
+When `TotalMixFX` is created, it reads the channel layout from TotalMix:
+the names of the channels in each row (Input, Playback, and Output) and the
+number of faders per bank. These are available as `channel_names` and
+`bank_size`:
+
+```python
+>>> tmfx.channel_names['Output']
+['Analog 1', 'Analog 2', ..., 'ADAT 3', 'ADAT 4']
+>>> tmfx.bank_size
+8
+```
+
+Reading the layout rather than configuring it has two purposes. It checks
+that TotalMix is reachable, raising `TotalMixError` straight away if it
+isn't. It also gives the exact channel count, which differs between
+devices and, for some, between sample rates (see
+[The channel count can depend on sample rate](#the-channel-count-can-depend-on-sample-rate)).
+Selecting a channel past the end of a row can crash TotalMix, so every
+channel number is checked against this layout before anything is sent,
+raising `ValueError` if it is out of range.
+
+Feedback is matched to channels by name, so channel names must be unique
+within each row. `TotalMixFX` raises `TotalMixError` if they aren't. This
+only matters if you've renamed channels in TotalMix.
+
+## Reading the mixer state
+
+`get_gain`, `get_crosspoint`, and `get_loopback` read the current state
+from TotalMix, for example to log the mixer configuration alongside
+acquired data:
+
+```python
+tmfx.get_gain(1)                        # -6.0
+tmfx.get_crosspoint(1, 'Playback', 1)   # 0.0
+tmfx.get_crosspoint(1, 'Input', 3)      # -inf
+tmfx.get_loopback(9)                    # True
+```
+
+## Loopback
+
+`set_loopback` turns loopback on or off for a hardware output, so the
+signal sent to that output is also returned to the computer as a recording
+input, replacing the matching hardware input. This is useful for recording
+the stimulus that was actually played. `get_loopback` reads back the
+current state.
+
+TotalMix's `/2/loopback` is a toggle button, not a setter, so
+`set_loopback` reads the current state first and only presses the
+button if needed, which makes repeated calls safe.
+`set_mono_straight_playback` does not change loopback.
+
+## Key concepts
+
+**Full reconstruction, not incremental changes**
+
+`set_mono_straight_playback` does not check what TotalMix's routing matrix
+currently looks like -- it overwrites every crosspoint it's responsible
+for on every call. This makes it self-healing: it doesn't matter whether
+the previous state came from a clean run, a manual experiment in the GUI,
+or a half-finished OSC script -- the result after calling it is always the
+same.
+
+**Verified writes**
+
+OSC runs over UDP, which is fire-and-forget: a dropped packet, a disabled
+"OSC Control" setting, or a wrong IP/port all look identical to Python --
+the send call still returns normally. To avoid silently trusting a command
+that had no effect, every change blocks until TotalMix's OSC feedback
+confirms the new value, and raises `TotalMixError` if that confirmation
+doesn't arrive within `timeout` seconds or doesn't match what was
+requested. Feedback only counts as confirmation once TotalMix has also
+confirmed which channel it describes (see
+[Changing a selector triggers a burst of feedback](#changing-a-selector-triggers-a-burst-of-feedback)).
+
+**Routing matrix vs. master gain**
+
+`set_crosspoint` controls an individual cell of the routing matrix (how
+much of one input/playback channel is fed into one output channel).
+`set_gain` controls an output channel's master fader -- the gain applied
+after routing/mixing. Under a straight 1:1 routing, `set_gain` is the
+natural place for per-experiment calibration offsets, since each output
+only receives one playback channel.
+
+## Legacy OSC protocol quirks
+
+The legacy protocol has no complete official spec. These notes are what
+we found testing against a Fireface UCX II running TotalMix FX 1.98 at
+96 kHz (16 channels per row: Analog 1-6, Phones L/R, SPDIF L/R, AES L/R,
+ADAT 1-4). Each entry says whether it was verified on hardware, and
+credits the
+[Bitfocus Companion TotalMix module](https://github.com/bitfocus/companion-module-rme-totalmix),
+the most thorough open implementation of this protocol, where it
+documents the same behavior.
+
+### Numeric arguments must be float32
+
+TotalMix reads every numeric argument as a 32-bit float, including
+selectors and buttons whose values are whole numbers. An OSC int is
+misread rather than rejected: `/setSubmix 2` (int) selected the first
+submix, while `/setSubmix 2.0` (float) selected the third. Python's
+`python-osc` sends a Python `int` as an OSC int, so `OSCClient` converts
+every number to a float before sending. *Verified; Companion encodes all
+numbers as float32 and notes that TotalMix documents this.*
+
+### Faders are addressed by bank, not by channel
+
+`/1/volumeN` only reaches strips 1 to N of the current bank, where N is
+"Number of faders per bank" in Settings > OSC (default 8). To reach other
+channels, select the bank with `/setBankStart`, which takes the
+**0-indexed** first channel of the bank and rounds down to a bank
+boundary (`/setBankStart 12.0` with 8-wide banks selects channel 9
+onward). `/setSubmix` is also 0-indexed, but `/1/volumeN` strip numbers
+start at 1. `TotalMixFX` reads the bank size from TotalMix and converts
+between these and its own 1-indexed channel numbers. *Verified.*
+
+### Selecting a bank past the last channel can crash TotalMix
+
+TotalMix FX 1.98 crashed (access violation `0xc0000005`) while we were
+enumerating channels by sending `/setBankStart` with increasing values up
+to 64, well past the 16 channels it exposed. We did not isolate exactly
+which message caused it. An out-of-range `/setSubmix` may also be unsafe.
+`TotalMixFX` reads the layout with `/1/bank+` instead, which stops at the
+last bank rather than overrunning, and refuses any channel outside that
+layout before anything is sent. *Observed once; trigger not isolated.*
+
+### The channel count can depend on sample rate
+
+Companion's profile for the UCX II lists 20 channels per row (ADAT 1-8),
+but at 96 kHz TotalMix exposed only 16 (ADAT 1-4). This is consistent
+with ADAT switching to S/MUX at double sample rates, which halves its
+channel count. A fixed per-device channel count is therefore not enough
+to guard against the crash above, which is why `TotalMixFX` reads the
+layout from TotalMix at startup. Slots past the end of a row are named
+`n.a.`; Companion discards them the same way. *Inferred; we have not yet
+compared sample rates directly.*
+
+### Changing a selector triggers a burst of feedback
+
+Selecting a bus (`/1/busInput`, `/1/busPlayback`, `/1/busOutput`), bank
+or submix makes TotalMix send back the full state of the newly selected
+bank: about 110 messages on page 1, about 85 on page 2. Some changes
+produce two bursts, and the first can still reflect the previous bus.
+Bursts from an earlier command can also still be arriving after the next
+command is sent. A burst lists every strip's value first and the strip
+names last, so a value alone doesn't say which channel it belongs to.
+
+`TotalMixFX` therefore only trusts a strip's value once the same burst
+has also reported the expected bus, submix label (for crosspoints), and
+channel name for that strip. After that, further values for the strip
+(the reply to a write) belong to the same selection. *Verified; Companion
+documents the same bursts and also ignores stale values.*
+
+### Message order within a burst matters
+
+A burst is a series of separate UDP messages, and their order carries
+meaning. For example, a page-2 burst sends a channel's `/2/loopback`
+before its `/2/trackname`, so the name tells you which channel the
+loopback value belonged to. `python-osc`'s `ThreadingOSCUDPServer`
+handles each message on its own thread, so handlers can run out of
+order. This only showed up once logging slowed some handlers down.
+`OSCClient` therefore uses `BlockingOSCUDPServer`, which handles messages
+one at a time in arrival order. *Verified.*
+
+### Page-2 buttons toggle instead of setting
+
+On page 2 (per-channel settings), buttons such as `/2/loopback` toggle
+when sent `1.0`, and `0.0` does nothing. Sending `1.0` twice turns
+loopback on and then off again. To set a state rather than flip it, read
+the current value first and only send `1.0` if it differs.
+`set_loopback` does this. *Verified for loopback; Companion treats all
+legacy toggle-style parameters this way.*
+
+### Selecting a channel on page 2
+
+Page 2 shows one channel at a time: the strip at `/setOffsetInBank`
+(0-indexed) within the current bank. For example, `/setBankStart 8.0`,
+`/setOffsetInBank 7.0`, `/2/busOutput 1.0` selects channel 16. Selecting a
+bank resets the offset to 0, and `/2/track+` and `/2/track-` step one
+channel at a time. *Verified; `/setOffsetInBank` learned from Companion.*
+
+### Where feedback is sent
+
+TotalMix sends feedback to the "Remote Controller" IP set in Settings >
+OSC, on the outgoing port (9001 by default). On our machine that was the
+host's network address, not `127.0.0.1`, so a listener bound only to
+loopback received nothing. `OSCClient` binds to the host's address by
+default, which matches. Only one process can listen on the feedback port.
+*Address verified; the port conflict is noted by Companion.*
+
+### Minor details
+
+* TotalMix reports unity gain as `-0.0 dB` after some writes and
+  `0.0 dB` after others. They parse to the same float, but direct string
+  comparisons will treat them as different.
+* "Send Level Data" in Settings > OSC adds a steady stream of meter
+  messages. `TotalMixFX` doesn't need them; turn it off to reduce traffic.
+* A verified fader write takes about 10-50 ms locally.
+  `set_mono_straight_playback` on 16 channels (528 writes) takes about
+  10 s.
+
+## Design notes
+
+TotalMix FX 2.1 adds "Global OSC", which addresses every fader and setting
+directly (e.g., `/mix/in/3/8/faderlin`) instead of through bus, bank, and
+submix selection. It avoids most of the quirks above, but is still in beta
+and the devices we use run older TotalMix versions. The public API (bus
+names, 1-indexed channel numbers, dB values, explicit `get_*`/`set_*`
+methods) is deliberately independent of the legacy addressing scheme, so
+that a Global OSC backend can be added later without changing it.
+
+## Known limitations
+
+* Matrix crosspoint control relies on TotalMix's `/setSubmix` command,
+  which is documented mainly through the RME user forum rather than an
+  official spec.
+* Stereo-paired channels have not been tested; the devices we tested on
+  had all channels set to mono.
+* Tested only on a Fireface UCX II with TotalMix FX 1.98.

totalmix_osc-0.0.1/docs/index.md

@@ -0,0 +1,21 @@
+# totalmix-osc
+
+Verified control of RME TotalMix FX routing, gains, and loopback over OSC.
+
+TotalMix FX is the mixer software for RME audio interfaces. Its state can
+be changed by a stray click, which breaks experiments that assume a
+known-good mixer configuration. `totalmix-osc` sets the routing matrix,
+output gains, and loopback from Python, and confirms every change with
+TotalMix before returning.
+
+## Installing
+
+```bash
+pip install totalmix-osc
+```
+
+## Contents
+
+* The [Guide](guide.md) covers setup, usage, and the quirks of TotalMix's
+  OSC protocol that this package works around.
+* The [API reference](api.md) is generated from docstrings.

totalmix_osc-0.0.1/examples/reset_routing.py

@@ -0,0 +1,24 @@
+import logging
+
+from totalmix_osc import TotalMixFX
+
+
+def main():
+    logging.basicConfig(level='INFO')
+
+    # Uses the default ports (7001/9001) and this machine's IP. Pass
+    # ip_address explicitly if TotalMix is running on a different machine.
+    tmfx = TotalMixFX()
+
+    # Primary use case: wipe out whatever routing/gain state TotalMix is
+    # currently in and reconstruct straight 1:1 mono playback from
+    # scratch, regardless of what a stray click may have changed.
+    tmfx.set_mono_straight_playback()
+
+    # Per-experiment gain, applied on top of the straight routing above.
+    tmfx.set_gain(1, -6.0)
+    tmfx.set_gain(2, -6.0)
+
+
+if __name__ == '__main__':
+    main()