ox1audio 0.3.5__py3-none-any.whl

ox1audio/AGENTS.md

@@ -0,0 +1,96 @@
+# Building a Mixel app
+
+This folder is one app: Python actions that Mixel runs on the person's computer. Use only the API on this page. Don't read the SDK source.
+
+## Loop
+1. Edit `app.py`. If what the code touches changes, update `app.json` › `permissions`.
+2. `mixel check` until it reports no errors. Each error ends with a `fix:` line; do that. `--fix` adds missing permissions and packages.
+3. `mixel test` runs `tests/`. `mixel run ACTION --file song.wav --set NAME=VALUE` runs one action on a real file.
+4. `mixel dev` opens the app in Mixel and reloads it on save. Never `mixel publish`, or change permissions, unless the person asks.
+
+## An action
+```python
+import ox1audio as ox
+
+@ox.action("Convert")
+def convert(files: ox.Files("audio"), format: ox.Choice("wav", "flac", "mp3") = "wav"):
+    made = []
+    for i, path in enumerate(files):             # each path is a pathlib.Path
+        ox.progress(i / len(files), path.name)   # Stop takes effect here
+        out = ox.audio.convert(path, format)     # a new file, in a temporary folder
+        made.append(ox.sound(out, title=path.stem))
+    return made                                  # sounds are added to the Library
+```
+- One decorated function per action. The parameters are the controls; Python defaults are their defaults. Mixel draws the form, checks the input, runs the action in the background, and shows progress and Stop.
+- Controls: `ox.Files("audio" | "midi" | "any", multiple=True)` gives `list[Path]` (one `Path` with `multiple=False`), `ox.Folder()` gives a `Path`, `ox.Choice("a", "b")` a `str`, `ox.Text(placeholder="")`, `ox.Number(min, max, step)`, `ox.Slider(min, max, step)` (`int` if all three are ints), `ox.Range(min, max, step)` → `(low, high)`, `ox.Toggle`. Number, Slider, Range take `unit="dB"`. Plain `str`/`int`/`float`/`bool` work too. Every control takes `label=`. `ox.Folder() | None = None` makes one optional. Save beside an input with `folder or ox.beside(path)` (`None` for a read-only Open with file: copies go to the Library).
+- Return `None`, a `str` (shown to the person), a JSON-able `dict` or `list` (for a page), or `ox.sound(path, title)`, `ox.midi(...)`, `ox.file(...)`, or a list of those. Metadata (`bpm=120, key="A minor"`) follows the title.
+- `ox.progress(fraction, label)`: fraction 0 to 1, or `None` when unknown. Call it often, also from library callbacks. When the person presses Stop it raises `ox.Cancelled` (a `BaseException`, so `except Exception` doesn't catch it): clean up in `except ox.Cancelled:` and re-raise. Every `ox.sound/midi/file` made so far is kept in the Library.
+- A problem the person can fix: `raise ox.Problem("That file has no audio.", hint="Try a WAV or MP3.")`. Other exceptions show "The app ran into a problem"; details go to the log.
+- `print` goes to the log. Don't write a server, threads, or `if __name__ == "__main__"`: Mixel runs the actions.
+
+## Testing
+```python
+import unittest
+
+import ox1audio as ox
+import app
+
+class ConvertTest(unittest.TestCase):
+    def test_converts_to_wav(self):
+        run = ox.test(app.convert, files=["tests/tone.wav"], format="wav")
+        self.assertEqual(run["items"][0]["title"], "tone")  # what reached the Library
+```
+`ox.test` returns `{"result", "items", "progress", "events"}`: what a page gets, the Library items, each `(fraction, label)` and `(name, body)`. `stop_at=0.5` presses Stop halfway: it raises `ox.Cancelled`, whose `.kept` lists what was kept. `ox.Problem` is raised as is.
+
+## Helpers
+| Need | Use |
+| --- | --- |
+| File info | `ox.audio.probe(path)` → `.rate .channels .duration .codec` |
+| Another format | `ox.audio.convert(path, "wav" / "aiff" / "flac" / "mp3" / "aac" / "ogg" / "opus", folder=None, bits=None)` → `Path` (keeps depth, tags, cover, loops; `.note` if it lowered an over) |
+| Samples (numpy) | `ox.audio.read(path)` → `(samples, rate)`, float32 `(frames, channels)`; `ox.audio.write(samples, rate, "wav", folder=None, name="audio", bits=24)` → `Path`. `bits=32`: float; 16 dithers. Over ±1 raises, with the fix. |
+| A folder for new files | `ox.temp()` → an empty folder, removed when the app closes |
+| The app's own files | `ox.data.read / read_text / write / list / remove("presets/a.json")` (needs `data`) |
+
+## app.json
+```json
+{
+  "$schema": "https://0x1audio.com/schema/app/v1.json",
+  "name": "my-converter",
+  "displayName": "My Converter",
+  "summary": "One file to many formats at once.",
+  "version": "0.1.0",
+  "sdk": "^0.3",
+  "entry": "app.py",
+  "license": "Apache-2.0",
+  "permissions": {
+    "files": "Open the songs you choose.",
+    "library": "Save the converted copies to your Library."
+  },
+  "accent": "#20b4c4"
+}
+```
+- Permissions are binding: `files` (Files and Folder controls), `library` (returning sounds), `library-read` (a page lists it), `data` (`ox.data`), `gpu` (torch, onnxruntime), `network` as `{"why": "…", "hosts": ["example.com"]}`. Ask only for what the code uses. Each reason: one sentence (12–120 chars) saying why.
+- Optional: `icon` (a square `.svg`/`.png` in the app), `window` (`{"width", "height", "minWidth", "minHeight"}`), `tags` (up to 5), `license` (SPDX), `page` (below).
+- Raise `version` before each release. Never change `name`.
+
+## Dependencies
+Python packages go in `pyproject.toml` › `[project].dependencies`, wheels only; Mixel installs only those (`mixel check --fix` adds what the code imports, then runs `uv sync`; commit uv.lock). numpy and scipy are fine. The SDK already has ffmpeg; don't add ffmpeg wrappers, pydub, or requests. Never commit models, songs or files over 5 MB.
+
+## A page (only when the drawn form is not enough)
+`mixel new --page` adds one: Vite + React, built to `dist/index.html`. It uses `@0x1audio/design-system` and the same actions:
+```tsx
+import { ox } from "@0x1audio/sdk/page"
+import { ActionForm } from "@0x1audio/design-system"
+
+export const App = () => <ActionForm action="convert" />   // the form Mixel draws; build around it
+// your own controls: await ox.run("convert", { files, format }, { onProgress: (f, label) => {}, onEvent: (name, body) => {}, signal })
+```
+Page API: `ox.run`, `ox.actions`, `ox.files.pick / fromDrop / read / reveal`, `ox.library.list / add / file / onChange`, `ox.data.*`, `ox.app.open`. Errors are `OxError` with `.code` (`cancelled` after Stop, with `.kept`). `ox.emit("partial", body)` in Python reaches `onEvent`. Design-system components and tokens only, no hex colours. Mixel sets `.dark` on `<html>`: check both.
+
+## Words (what the person sees)
+Say what it does for a musician: song, sound, file, folder, Library. Never: worker, manifest, SDK, ffmpeg. Sentence case. Buttons are verbs. No exclamation marks. Errors say what happened, then what to do.
+
+## Never
+- Touch files other than the ones the person chose, files next to them, `ox.temp()` and `ox.data`.
+- Use `subprocess`, `os.system`, `eval`/`exec`, raw sockets, or telemetry.
+- Edit `AGENTS.md` or `dist/` by hand, or commit `.venv/` or `node_modules/`.

ox1audio/__init__.py

@@ -0,0 +1,83 @@
+"""Build Mixel apps: typed Python actions that run on the person's computer.
+
+    import ox1audio as ox
+
+    @ox.action("Make it louder")
+    def louder(files: ox.Files("audio"), gain: ox.Slider(0, 12, step=0.5) = 6.0):
+        ...
+
+The whole public API is ``__all__`` below. AGENTS.md in every app explains it.
+"""
+
+__version__ = "0.3.5"
+
+from ox1audio.action import Cancelled, Problem, action, beside, emit, progress, temp, test
+from ox1audio.app import run
+from ox1audio.fields import Choice, Files, Folder, Number, Range, Slider, Text, Toggle, file, midi, sound
+
+from . import audio, data, library
+
+__all__ = [
+    "Cancelled",
+    "Choice",
+    "Files",
+    "Folder",
+    "Number",
+    "Problem",
+    "Range",
+    "Slider",
+    "Text",
+    "Toggle",
+    "action",
+    "audio",
+    "beside",
+    "data",
+    "emit",
+    "file",
+    "library",
+    "midi",
+    "progress",
+    "run",
+    "sound",
+    "temp",
+    "test",
+]
+
+_DOCS = "https://docs.0x1audio.com"
+
+# Names that 0.2 had. Using one says what replaced it instead of a bare AttributeError.
+_removed = {
+    "screen": ('@ox.screen("Title") is now @ox.action("Title").', 'rename the decorator: @ox.action("Title")', "actions#an-action"),
+    "job": (
+        "@ox.job is gone: every @ox.action already runs in the background with progress and Stop.",
+        'use @ox.action("Title") with typed parameters, call ox.progress() as you go, and return the result',
+        "actions#progress-and-stop",
+    ),
+    "serve": (
+        "ox.serve is gone: Mixel finds your @ox.action functions and runs them.",
+        'decorate each handler with @ox.action("Title") and delete the serve({...}) call',
+        "actions#an-action",
+    ),
+    "Call": (
+        "The call object is gone: actions take typed parameters.",
+        "replace call.body[...] with parameters, call.progress(...) with ox.progress(...), and call.cancelled() with letting ox.Cancelled propagate",
+        "actions#controls",
+    ),
+    "exercise": ("ox.exercise is now ox.test.", "ox.test(action, files=[...])", "actions#testing"),
+    "convert": ("ox.convert is now ox.audio.convert.", 'ox.audio.convert(path, "wav")', "actions#helpers"),
+    "Client": ("The cloud client is not part of the app API.", "remove it; apps reach the cloud only through what Mixel allows", "permissions"),
+    "AuthenticatedClient": ("The cloud client is not part of the app API.", "remove it; apps reach the cloud only through what Mixel allows", "permissions"),
+}
+
+
+class RemovedError(ImportError):
+    """A name from an older SDK. The message says what to use instead."""
+
+
+def __getattr__(name: str) -> object:
+    found = _removed.get(name)
+    if found is None:
+        raise AttributeError(f"module 'ox1audio' has no attribute {name!r}. The API is: {', '.join(__all__)}.")
+    problem, fix, page = found
+    # ImportError (not AttributeError), so `from ox1audio import job` shows this message too.
+    raise RemovedError(f"{problem}\nfix:  {fix}\ndocs: {_DOCS}/{page}", name=name)

ox1audio/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m ox1audio app.py`` loads the app and serves its actions over stdin and stdout."""
+
+import sys
+
+from ox1audio.app import main
+
+if len(sys.argv) != 2:
+    print("usage: python -m ox1audio app.py   (Mixel runs this for you; to try an action use ox.test)", file=sys.stderr)
+    raise SystemExit(2)
+raise SystemExit(main(sys.argv[1]))

ox1audio/_contract.py

@@ -0,0 +1,26 @@
+"""Generated from sdk-py/contract by contract/generate.py. Do not edit.
+
+The app.json rules, permission codes, protocol version and error codes, in one place."""
+
+SCHEMA = "https://0x1audio.com/schema/app/v1.json"
+FIELDS = ["$schema", "name", "displayName", "summary", "version", "sdk", "entry", "page", "permissions", "accent", "icon", "window", "tags", "license"]
+REQUIRED = ["$schema", "name", "displayName", "version", "sdk"]
+PERMISSIONS = ["files", "library", "library-read", "data", "gpu", "network"]
+PERMISSION_TEXT = {"files": "Read and write files you pick", "library": "Add to your Library", "library-read": "Read your Library", "data": "Keep its own files", "gpu": "Use the graphics chip", "network": "Use the network"}
+NAME_PATTERN = "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+NAME_LENGTH = [2, 48]
+DISPLAY_NAME_MAX = 48
+SUMMARY_MAX = 80
+VERSION_PATTERN = "^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$"
+SDK_PATTERN = "^\\^(0|[1-9][0-9]{0,3})\\.(0|[1-9][0-9]{0,3})(\\.(0|[1-9][0-9]{0,3}))?$"
+ACCENT_PATTERN = "^#[0-9a-fA-F]{6}$"
+HOST_PATTERN = "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$"
+HOSTS_MAX = 16
+REASON_LENGTH = [12, 120]
+WINDOW = {"width": [400, 2560], "height": [320, 1600], "minWidth": [400, 2560], "minHeight": [320, 1600]}
+TAGS_MAX = 5
+LICENSE_PATTERN = "^[A-Za-z0-9.+-]+(?: (?:AND|OR|WITH) [A-Za-z0-9.+-]+)*$"
+PROTOCOL = 1
+CONTROLS = ["files", "folder", "choice", "text", "number", "slider", "toggle"]
+RUN_ERRORS = ["bad_input", "problem", "cancelled", "crashed", "timeout", "permission_denied", "permission_undeclared", "unavailable"]
+ERRORS = {"manifest_missing": {"area": "check", "means": "There is no app.json in the folder.", "fix": "mixel new \"My App\" starts one.", "severity": "error"}, "manifest_json": {"area": "check", "means": "app.json is not valid JSON.", "fix": "Fix the JSON at the line shown.", "severity": "error"}, "manifest_v0": {"area": "check", "means": "app.json has no \"$schema\": it is the old v0 format.", "fix": "Add \"$schema\" and \"sdk\", rename worker.entry to entry and frontend to page, give each permission a reason.", "severity": "error"}, "manifest_schema": {"area": "check", "means": "\"$schema\" is not the v1 URL.", "fix": "\"$schema\": \"https://0x1audio.com/schema/app/v1.json\"", "severity": "error"}, "manifest_field": {"area": "check", "means": "A field app.json doesn't have, or one that was renamed.", "fix": "Remove or rename it as the message says.", "severity": "error"}, "manifest_name": {"area": "check", "means": "name is not 2 to 48 lowercase letters, digits and dashes.", "fix": "\"name\": \"my-app\". It never changes after the first publish.", "severity": "error"}, "manifest_display_name": {"area": "check", "means": "displayName is missing or over 48 characters.", "fix": "\"displayName\": \"My App\"", "severity": "error"}, "manifest_summary": {"area": "check", "means": "summary is not one sentence of up to 80 characters.", "fix": "\"summary\": \"One file to many formats at once.\"", "severity": "error"}, "manifest_version": {"area": "check", "means": "version is not MAJOR.MINOR.PATCH, or not above the last published one.", "fix": "\"version\": \"0.1.0\", raised before each publish.", "severity": "error"}, "manifest_entry": {"area": "check", "means": "entry is missing, not a .py file, or not in the app.", "fix": "\"entry\": \"app.py\"", "severity": "error"}, "manifest_page": {"area": "check", "means": "page is not an .html file in the app, or it isn't built.", "fix": "npm run build, then \"page\": \"dist/index.html\"", "severity": "error"}, "manifest_accent": {"area": "check", "means": "accent is not a colour like #5b8cff.", "fix": "\"accent\": \"#5b8cff\"", "severity": "error"}, "manifest_icon": {"area": "check", "means": "icon is not a square .svg or .png in the app.", "fix": "\"icon\": \"icon.svg\"", "severity": "error"}, "manifest_window": {"area": "check", "means": "window sizes are whole pixels within the allowed range.", "fix": "\"window\": { \"width\": 900, \"height\": 640 }", "severity": "error"}, "manifest_license": {"area": "check", "means": "license is not an SPDX identifier.", "fix": "\"license\": \"Apache-2.0\" (or MIT, GPL-3.0-only, ...)", "severity": "error"}, "manifest_tags": {"area": "check", "means": "tags is more than 5 single words.", "fix": "\"tags\": [\"convert\"]", "severity": "error"}, "sdk_missing": {"area": "check", "means": "app.json has no sdk range.", "fix": "\"sdk\": \"^0.3\"", "severity": "error"}, "sdk_range": {"area": "check", "means": "sdk is not a caret range this SDK satisfies.", "fix": "\"sdk\": \"^0.3\"", "severity": "error"}, "permission_undeclared": {"area": "run", "means": "The app used a permission app.json doesn't declare. Declared is binding.", "fix": "Add it to app.json › permissions with a reason.", "severity": "error"}, "permission_unused": {"area": "check", "means": "app.json asks for a permission the code doesn't use.", "fix": "Remove it, so people aren't asked for more than the app needs.", "severity": "warn"}, "template_words": {"area": "check", "means": "The summary or a permission reason is still mixel new's words about converting, in an app that does something else.", "fix": "Write what your app does, and why it needs each permission, in your own words.", "severity": "warn"}, "permission_unknown": {"area": "check", "means": "Not a permission. They are files, library, library-read, data, gpu and network.", "fix": "Use one of files, library, library-read, data, gpu, network.", "severity": "error"}, "permission_reason": {"area": "check", "means": "A permission without a reason of 12 to 120 characters.", "fix": "One sentence that tells the person why, like \"Open the songs you choose.\"", "severity": "error"}, "network_hosts": {"area": "check", "means": "network without a list of hosts, or with the whole web, an IP or localhost.", "fix": "\"network\": { \"why\": \"Download the model once.\", \"hosts\": [\"github.com\"] }", "severity": "error"}, "dependency_missing": {"area": "check", "means": "The code imports a package pyproject.toml doesn't list, so Mixel won't install it.", "fix": "Add it to pyproject.toml › [project].dependencies.", "severity": "error"}, "dependency_not_installed": {"area": "check", "means": "A listed package isn't installed where mixel runs, so the actions couldn't be loaded.", "fix": "uv sync (mixel check --fix runs it)", "severity": "error"}, "lock_missing": {"area": "check", "means": "pyproject.toml lists packages but there is no uv.lock, so Mixel and the registry can't install exactly what was reviewed.", "fix": "uv lock, then commit uv.lock. mixel check --fix runs it.", "severity": "error"}, "banned_api": {"area": "check", "means": "The code runs programs, opens raw sockets, runs code from strings, or imports by a name it builds (subprocess, os.system, socket, ctypes, eval, exec, __import__, requests).", "fix": "Use ox.audio.convert, ox.audio.read or ox.audio.write instead of programs; urllib.request with a declared network for downloads; plain imports.", "severity": "error"}, "path_outside": {"area": "check", "means": "The code opens a fixed path outside the app, like /etc/passwd, /tmp or the home folder.", "fix": "Use the files the person chooses (ox.Files, ox.Folder), ox.temp() or ox.data.", "severity": "error"}, "app_failed_to_load": {"area": "check", "means": "The entry file raised an error while loading.", "fix": "Fix the error at the line shown; the message names the fix.", "severity": "error"}, "no_actions": {"area": "check", "means": "The entry file has no @ox.action functions.", "fix": "@ox.action(\"Title\") above a function makes it an action.", "severity": "error"}, "bad_input": {"area": "run", "means": "The input doesn't fit the action's controls. Python never sees it.", "fix": "Send each control's value, as the message says.", "severity": "error"}, "problem": {"area": "run", "means": "The action raised ox.Problem: something the person can fix.", "fix": "Show the message and hint to the person.", "severity": "error"}, "cancelled": {"area": "run", "means": "The person pressed Stop. kept lists what the action finished before.", "fix": "Nothing to fix. Show what was kept.", "severity": "error"}, "crashed": {"area": "run", "means": "The action raised an unexpected error, or the app stopped.", "fix": "Read the log (mixel dev prints it), fix the line, run again.", "severity": "error"}, "timeout": {"area": "run", "means": "The action ran longer than its timeout.", "fix": "@ox.action(\"Title\", timeout=3600), and call ox.progress so Stop works.", "severity": "error"}, "permission_denied": {"area": "run", "means": "The page used a file the person didn't choose, or a permission they turned off.", "fix": "Use ox.files.pick or a Files control; ask the person to allow it.", "severity": "error"}, "unavailable": {"area": "run", "means": "The page isn't running inside Mixel, or the app has no actions.", "fix": "Open the app in Mixel (mixel dev).", "severity": "error"}, "usage": {"area": "cli", "means": "The command line is wrong.", "fix": "mixel --help", "severity": "error"}, "folder_not_empty": {"area": "cli", "means": "mixel new would write into a folder that has files.", "fix": "Choose another name.", "severity": "error"}, "no_tests": {"area": "cli", "means": "There are no tests in tests/.", "fix": "Add tests/test_app.py with a unittest that calls ox.test(...).", "severity": "error"}, "tests_did_not_run": {"area": "cli", "means": "The test runner itself failed.", "fix": "Run python -m unittest in the app's folder to see the whole error.", "severity": "error"}, "no_such_action": {"area": "cli", "means": "mixel run named an action the app doesn't have.", "fix": "Use a name mixel check lists.", "severity": "error"}, "no_such_topic": {"area": "cli", "means": "mixel docs named a page that doesn't exist.", "fix": "mixel docs --list", "severity": "error"}, "desktop_unavailable": {"area": "cli", "means": "Mixel isn't running, or developer mode is off.", "fix": "Open Mixel, turn on Settings › Developer mode, then quit and reopen Mixel.", "severity": "error"}, "desktop_error": {"area": "cli", "means": "The desktop refused or failed a dev request.", "fix": "Follow the message; mixel doctor checks the setup.", "severity": "error"}, "not_signed_in": {"area": "cli", "means": "No sign-in, or it expired.", "fix": "mixel login", "severity": "error"}, "expired_token": {"area": "cli", "means": "The pairing code expired before it was confirmed.", "fix": "mixel login", "severity": "error"}, "network": {"area": "cli", "means": "Mixel's cloud couldn't be reached.", "fix": "Check the connection. MIXEL_API sets another address.", "severity": "error"}, "registry_unavailable": {"area": "cli", "means": "This cloud doesn't take that request from the CLI yet.", "fix": "Update the server, or set MIXEL_API.", "severity": "error"}, "registry_error": {"area": "cli", "means": "The registry refused the request.", "fix": "Follow the message and its doc link.", "severity": "error"}, "git_missing": {"area": "cli", "means": "git isn't installed.", "fix": "Install git.", "severity": "error"}, "git_failed": {"area": "cli", "means": "A git command failed.", "fix": "The app's folder must be a git repository pushed to GitHub.", "severity": "error"}, "git_dirty": {"area": "cli", "means": "There are changes that aren't committed.", "fix": "git add -A && git commit -m \"…\" && git push", "severity": "error"}, "git_not_pushed": {"area": "cli", "means": "The commit isn't on GitHub yet.", "fix": "git push", "severity": "error"}, "not_repo_root": {"area": "cli", "means": "The app isn't at the top of its git repository.", "fix": "Give the app its own repository.", "severity": "error"}, "not_github": {"area": "cli", "means": "The remote isn't a GitHub repository.", "fix": "Push the app to a public GitHub repository.", "severity": "error"}, "library_search_off": {"area": "library", "means": "Mixel is closed, or Let an assistant search your Library is off.", "fix": "The person opens Mixel and turns it on in Settings › Your assistant.", "severity": "error"}, "not_ready": {"area": "library", "means": "Mixel can't compare sounds yet: the sound model is off or still indexing. Search by words still works.", "fix": "Search with words instead, or ask the person to check Mixel.", "severity": "error"}, "unknown_id": {"area": "library", "means": "An id that no search in this Mixel session returned, or one it no longer remembers.", "fix": "Search again and use the ids it returns.", "severity": "error"}, "too_many": {"area": "library", "means": "More than a search or a crate takes: 5 avoid or unlike words, 50 sounds in a crate.", "fix": "Keep the ones that matter most.", "severity": "error"}, "crates_off": {"area": "library", "means": "Proposing crates is off in this Mixel, so nothing was made.", "fix": "Tell the person what you found; they can turn on Settings › Your assistant › It can propose crates.", "severity": "error"}, "unknown_tool": {"area": "library", "means": "Mixel has no tool by that name.", "fix": "Use library_overview, library_search or propose_crate.", "severity": "error"}, "too_long": {"area": "library", "means": "Mixel's answer was over its limit, so it wasn't sent.", "fix": "Ask for less: fewer words, or a narrower filter.", "severity": "error"}, "mixel_error": {"area": "library", "means": "Mixel couldn't answer, for a reason it keeps to itself.", "fix": "Try again; if it keeps failing, tell the person.", "severity": "error"}, "github_required": {"area": "registry", "means": "The Mixel account has no GitHub account connected, and reviewers read the code there.", "fix": "Connect GitHub on your account page, then publish again.", "severity": "error"}, "repository_invalid": {"area": "registry", "means": "repository isn't a GitHub repository like github.com/owner/repo.", "fix": "Push the app to GitHub and publish from its folder.", "severity": "error"}, "repository_not_yours": {"area": "registry", "means": "The repository isn't one of the public repositories GitHub shows for the connected account.", "fix": "Push the app to a public repository you own, or connect the GitHub account that owns it.", "severity": "error"}, "commit_invalid": {"area": "registry", "means": "commit isn't the full 40-character SHA of a commit.", "fix": "git rev-parse HEAD", "severity": "error"}, "commit_not_pushed": {"area": "registry", "means": "The commit isn't on GitHub yet.", "fix": "git push", "severity": "error"}, "message_invalid": {"area": "registry", "means": "The note for reviewers is over 500 characters.", "fix": "Shorten it.", "severity": "error"}, "submission_pending": {"area": "registry", "means": "A version of this app is already waiting for review.", "fix": "mixel status shows it; publish again once it is decided.", "severity": "error"}, "app_required": {"area": "registry", "means": "The request doesn't name the app.", "fix": "Name it as app.json does: mixel status in the app's folder does this.", "severity": "error"}, "rate_limited": {"area": "registry", "means": "Too many requests in a short time, like more than 10 submissions in an hour.", "fix": "Wait, then try again; the message says how long.", "severity": "error"}, "waitlisted": {"area": "registry", "means": "The account is on the waitlist, so only sign-in, sign-out and the account's own data answer.", "fix": "Wait for the email that says you're in.", "severity": "error"}, "terms_required": {"area": "registry", "means": "The account hasn't agreed to the Terms of Service.", "fix": "Open cloud.0x1audio.com, agree, then run mixel login again.", "severity": "error"}, "plan_required": {"area": "registry", "means": "The account's plan doesn't include this; the error names what it needs.", "fix": "See the plans on your account page.", "severity": "error"}}

ox1audio/_protocol.py

@@ -0,0 +1,236 @@
+"""The worker side of protocol 1. Internal: apps never import this.
+
+NDJSON on stdin and stdout, one JSON object per line. Stdout carries only the
+protocol; ``print`` goes to stderr. Host call ids (``id``) and worker request
+ids (``rid``) are separate spaces. The message shapes live in one place, the
+``Message`` docstring below, so GAB-37 can generate them from a contract.
+
+Worker -> host
+    {"type": "ready", "protocol": 1, "sdk": "0.3.0", "actions": [ActionSpec], "permissions": ["files"]}
+    {"type": "fatal", "error": Error}                         the app could not load; the worker exits
+    {"type": "progress", "id": 7, "fraction": 0.4 | null, "label": "Separating vocals"}
+    {"type": "event", "id": 7, "name": "partial", "body": ...}  ox.emit; the host forwards it to the page that made call 7
+    {"type": "result", "id": 7, "body": ...}
+    {"type": "error", "id": 7, "error": Error}
+    {"type": "library", "rid": 3, "op": "add", "kind", "path", "title", "metadata"}
+    {"type": "cloud", "rid": 4, "method", "path", "body"}
+
+Host -> worker
+    {"type": "call", "id": 7, "action": "convert", "input": {...}, "handed"?: [path]}   handed: files from "Open with"
+    {"type": "cancel", "id": 7}
+    {"type": "library-result", "rid": 3, "status": 200, "body": {...}}
+    {"type": "cloud-result", "rid": 4, "status": 200, "body": {...}}
+    {"type": "shutdown"}
+
+Error = {"code": "bad_input" | "problem" | "cancelled" | "crashed", "message": str, "hint"?: str, "detail"?: str,
+         "kept"?: [Item]}   kept: on "cancelled", what the action finished before Stop (already in the Library)
+ActionSpec = {"name", "title", "input": JSON Schema (object), "timeout": seconds}
+"""
+
+from __future__ import annotations
+
+import contextvars
+import json
+import queue
+import sys
+import threading
+import traceback
+from collections.abc import Iterable
+from typing import BinaryIO
+
+from ox1audio import __version__, _contract
+from ox1audio.action import Action, BadInput, Cancelled, Problem, call, stopped_message
+from ox1audio.runtime import link_var
+
+PROTOCOL = _contract.PROTOCOL
+
+
+class Link:
+    def __init__(self, stdin: BinaryIO, stdout: BinaryIO) -> None:
+        self._stdin = stdin
+        self._stdout = stdout
+        self._write_lock = threading.Lock()
+        self._lock = threading.Lock()
+        self._next = 1
+        self._pending: dict[int, queue.Queue[dict]] = {}
+        self._incoming: queue.Queue[dict | None] = queue.Queue()
+        self.reader = threading.Thread(target=self._read, name="ox1audio-link", daemon=True)
+        self.reader.start()
+
+    def next_message(self) -> dict | None:
+        return self._incoming.get()
+
+    def send(self, message: dict) -> None:
+        data = json.dumps(message, separators=(",", ":"), allow_nan=False).encode() + b"\n"
+        with self._write_lock:
+            self._stdout.write(data)
+            self._stdout.flush()
+
+    def request(self, message: dict) -> dict:
+        """Ask the host for something (library, cloud) and wait for its answer."""
+        with self._lock:
+            rid = self._next
+            self._next += 1
+            box: queue.Queue[dict] = queue.Queue(maxsize=1)
+            self._pending[rid] = box
+        self.send({**message, "rid": rid})
+        answer = box.get()
+        with self._lock:
+            self._pending.pop(rid, None)
+        if answer.get("type") == "closed":
+            raise ConnectionError("Mixel closed the app.")
+        return answer
+
+    def library(self, payload: dict) -> object:
+        answer = self.request({"type": "library", **payload})
+        status = int(answer.get("status") or 500)
+        body = answer.get("body")
+        if status >= 400:
+            text = body.get("message") if isinstance(body, dict) else ""
+            raise Problem(text or "Could not add that to the Library.")
+        return body
+
+    def _read(self) -> None:
+        while True:
+            line = self._stdin.readline()
+            if line == b"":
+                self._incoming.put(None)
+                with self._lock:
+                    boxes = list(self._pending.values())
+                for box in boxes:
+                    box.put({"type": "closed"})
+                return
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                print("The app ignored a line from Mixel that was not JSON.", file=sys.stderr)
+                continue
+            if not isinstance(message, dict):
+                continue
+            rid = message.get("rid")
+            if message.get("type") in {"library-result", "cloud-result"} and isinstance(rid, int):
+                with self._lock:
+                    box = self._pending.get(rid)
+                if box is not None:
+                    box.put(message)
+                continue
+            self._incoming.put(message)
+
+
+def ready(registered: Iterable[Action]) -> dict:
+    listed = list(registered)
+    needed: set[str] = set()
+    for act in listed:
+        needed |= act.permissions()
+    order = _contract.PERMISSIONS
+    return {
+        "type": "ready",
+        "protocol": PROTOCOL,
+        "sdk": __version__,
+        "actions": [act.spec() for act in listed],
+        "permissions": [code for code in order if code in needed],
+    }
+
+
+def serve(registered: Iterable[Action], *, stdin: BinaryIO | None = None, stdout: BinaryIO | None = None) -> None:
+    """Announce the actions, then run calls until the host closes the pipe or says shutdown."""
+    out = stdout or sys.stdout.buffer
+    if stdout is None:
+        sys.stdout = sys.stderr
+    link = Link(stdin or sys.stdin.buffer, out)
+    link_var.set(link)
+    by_name = {act.name: act for act in registered}
+    cancels: dict[int, threading.Event] = {}
+    link.send(ready(by_name.values()))
+    workers: list[threading.Thread] = []
+    while True:
+        message = link.next_message()
+        if message is None or message.get("type") == "shutdown":
+            # Shutdown stops what is running; at end of input, calls get the same few seconds to finish.
+            if message is not None:
+                for event in list(cancels.values()):
+                    event.set()
+            for thread in workers:
+                thread.join(timeout=3)
+            # Let the reader see the end of input before Python shuts down; a daemon thread
+            # still inside readline() at shutdown makes Python abort with a fatal error.
+            link.reader.join(timeout=0.5)
+            return
+        kind = message.get("type")
+        ident = message.get("id")
+        if kind == "cancel" and isinstance(ident, int):
+            event = cancels.get(ident)
+            if event is not None:
+                event.set()
+            continue
+        if kind != "call" or not isinstance(ident, int):
+            continue
+        name = message.get("action")
+        act = by_name.get(name) if isinstance(name, str) else None
+        if act is None:
+            link.send(_error(ident, "bad_input", f"This app has no action called {name}.", f"Its actions are: {', '.join(by_name) or 'none'}."))
+            continue
+        cancels[ident] = threading.Event()
+        thread = threading.Thread(
+            target=contextvars.copy_context().run,
+            args=(_run, link, act, ident, message.get("input"), cancels, message.get("handed")),
+            name=f"ox1audio-{act.name}-{ident}",
+            daemon=True,
+        )
+        thread.start()
+        workers = [item for item in workers if item.is_alive()] + [thread]
+
+
+def _run(link: Link, act: Action, ident: int, given: object, cancels: dict[int, threading.Event], handed: object = None) -> None:
+    cancel = cancels[ident]
+
+    def report(fraction: float | None, label: str) -> None:
+        link.send({"type": "progress", "id": ident, "fraction": fraction, "label": label})
+
+    def send(name: str, body: object) -> None:
+        link.send({"type": "event", "id": ident, "name": name, "body": body})
+
+    try:
+        body = call(act, given, ident=ident, cancel=cancel, report=report, send=send, handed=handed or ())
+        line = {"type": "result", "id": ident, "body": body}
+        if len(json.dumps(line, allow_nan=False)) > 1 << 20:
+            line = _error(ident, "crashed", "The result is too large to send.", detail=f"{act.name}() returned more than 1 MiB. Write large data to a file and return its path.")
+            print(line["error"]["detail"], file=sys.stderr)
+    except Cancelled as stop:
+        line = _error(ident, "cancelled", stopped_message(stop.kept))
+        if stop.kept:
+            line["error"]["kept"] = stop.kept
+    except Problem as problem:
+        line = _error(ident, "problem", problem.message, problem.hint)
+    except BadInput as bad:
+        line = _error(ident, "bad_input", str(bad))
+    except Exception as exc:
+        if cancel.is_set():
+            line = _error(ident, "cancelled", "Stopped.")
+        else:
+            traceback.print_exc(file=sys.stderr)
+            line = _error(ident, "crashed", "The app ran into a problem.", detail=f"{type(exc).__name__}: {exc}")
+    finally:
+        cancels.pop(ident, None)
+    try:
+        link.send(line)
+    except (BrokenPipeError, ValueError, OSError):
+        pass
+
+
+def _error(ident: int, code: str, message: str, hint: str | None = None, detail: str | None = None) -> dict:
+    error: dict = {"code": code, "message": message}
+    if hint:
+        error["hint"] = hint
+    if detail:
+        error["detail"] = detail
+    return {"type": "error", "id": ident, "error": error}
+
+
+def fatal(message: str, detail: str = "", *, stdout: BinaryIO | None = None) -> None:
+    out = stdout or sys.__stdout__.buffer
+    error = {"code": "crashed", "message": message}
+    if detail:
+        error["detail"] = detail
+    out.write(json.dumps({"type": "fatal", "error": error}).encode() + b"\n")
+    out.flush()