# Ewe Sound agent help ## Shared Ewe agent standard (version 1) Ewe Paint, Ewe Write and Ewe Sound use this same MCP and CLI contract. App-specific editing commands and file rules follow below. Both interfaces call the same live editor operations and share its state and undo history. ### Discover commands without opening the app The installation folder contains `AGENTS.md` (this guide), `tools.json` (the exact MCP tool schemas), `agent.json` (app identity and default port), `cli-help.txt`, and `ewe-cli.ps1`. No Node.js or AI client is needed for the CLI. ```powershell & '.\ewesound.exe' --help | Out-String & '.\ewesound.exe' --version | Out-String & '.\ewesound.exe' --guide | Out-String & '.\ewesound.exe' --list | Out-String powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Help powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Guide powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -List ``` These help/catalogue options exit without creating a window or enabling MCP. `--list` and `-List` return the same JSON tool array as MCP `tools/list`. `--guide`, `-Guide` and MCP `guide` return this same installed manual. `tools.json` owns the argument names, types, bounds and required fields. ### Control the existing editor ```powershell & '.\ewesound.exe' --agent powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Tool get_state powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Launch -Tool get_state powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Tool history -ArgumentsFile C:\path\history.json powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Tool NAME -ArgumentsFile C:\path\arguments.json ``` `--agent` enables the local HTTP MCP endpoint on the existing window, preserving its work, or opens the app if closed. The CLI attaches to an enabled endpoint or enables the existing instance. It opens a closed app only with `-Launch`. Calls leave the editor open. `-ConnectOnly` returns the verified endpoint URL. `-ExePath` chooses a development executable. The app-specific CLI/helper filenames remain compatible aliases of `ewe-cli.ps1`. Use an arguments file for reliable JSON input from any shell. For example, `history.json` contains `{"action":"list"}`. When calling the script directly inside PowerShell, `-Arguments '{"action":"list"}'` also accepts inline JSON. Default endpoint: `http://127.0.0.1:47818/mcp`. Select a different port at initial launch with `--mcp-http=PORT` or `EWESOUND_MCP_PORT`; pass the same port to the CLI with `-Port PORT`. A running instance retains its original port. `--new-window` opens an isolated instance for testing. Ports must be integers from 1 to 65535. ### Connect an MCP client For a client-owned window, configure the installed executable's absolute path: ```json {"mcpServers":{"ewesound":{"command":"C:\\path\\ewesound.exe","args":["--mcp"]}}} ``` `--mcp` uses newline-delimited JSON-RPC on stdin/stdout. Logs go to stderr. Closing stdin closes that isolated window. HTTP remains separate and is enabled with `--agent` or `--mcp-http[=PORT]`. For the existing editor, use Streamable HTTP at the endpoint above. Send `initialize`, `notifications/initialized`, then `tools/list` and `tools/call`. Supported protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. HTTP uses JSON POST responses; GET streaming is not supported. Tool failures return `isError:true`; protocol errors use JSON-RPC errors. The CLI prints the MCP result as JSON and exits 0 on success, 1 on an argument, connection, protocol or tool failure. Executable launch syntax errors exit 2. `--license` prints the software notice. ### Session and editing rules Read `guide` and `get_state` first. Preserve existing work; inspect the app-specific output after an edit. Use documented tools and their schemas. Commands run one at a time. A successful call does not imply a file was saved: use the app's explicit save command and inspect its result. Normal launches leave HTTP MCP off. Access lasts for the current session; disable it in the app's agent help or call `agent_control {"enabled":false}`. Stdio remains available to its owning client. The server binds only to loopback and checks Host and Origin. Any local program can use an enabled endpoint; it has no per-client login. Browser editions do not host an MCP server. Never infer that unsaved work may be discarded. Follow this app's units, selection, overwrite and save-copy rules below. ## Audio preparation and measurements `analyze_sound` measures the active sound, or `start`/`end` in seconds. It returns sample peak, RMS dBFS, DC offset per channel, near-full-scale sample/frame counts and longest consecutive runs. `threshold` defaults to 0.9999. `bins` (0..4096) adds per-channel min/max/RMS waveform bins with start/end times, preserving short transients. Silence's dB values are JSON null, not infinity. RMS is not LUFS and near-full-scale runs indicate possible saturation, not proof of recoverable audio. `prepare_clip` opens a NEW dirty tab and never edits or saves its source. Options: `at`, `secs`, `mono`, `sample_rate`, exactly one of `peak` (linear), `peak_db` or `rms` (linear); `edge` and `tail` in seconds; `loop` and `fade` for an equal-power loop crossfade. `peakOver:"recording"` keeps peak levels relative to the source. Defaults: whole sound, mono, 48000 Hz, -2 dBFS peak, 1 ms edges and 250 ms tail. The peak ceiling is 0.98; resampling occurs before leveling. Loop fades shorten the result by `fade` seconds and replace edge/tail fades. The result includes the recipe, measurements of the selected source interval and output measurements. The recipe refers to the current decoded samples, so keep the original source file and its SHA-256 if reproducing it elsewhere. Save the new tab explicitly with `save_sound` or the GUI. Original save handles and history remain untouched. `ffmpeg_info` reports the external executable path, version and licence. Desktop resampling requires an LGPL FFmpeg in `ffmpeg/bin` beside the app, or the folder selected by `EWESOUND_FFMPEG_DIR`. It is a replaceable external process, not linked into the app. Runtime does not download, overwrite or hash-lock it. A GPL or nonfree build is refused. See `ffmpeg/README.md` for replacement and distribution. The browser uses Web Audio's band-limited resampler instead. ```powershell .\ewesound-cli.ps1 -Tool analyze_sound -Arguments '{"bins":200}' .\ewesound-cli.ps1 -Tool prepare_clip -Arguments '{"at":1.73,"secs":2.27,"mono":true,"sample_rate":48000,"peak_db":-2,"edge":0.001,"tail":0.4}' node ewesound-audio.mjs analyze C:/Sounds/source.wav --bins 200 node ewesound-audio.mjs cut C:/Sounds/cuts.json --out C:/Sounds/clips ``` The Node runner accepts WAV input and version 1 `EweSoundCuts`/`SoundCuts` recipes with a `cuts` array. Each cut has a `file` relative to the recipe and a relative `.wav` `clip` under `--out`, followed by preparation options. It writes atomic PCM16 WAV copies. Replacing outputs requires `--overwrite`; source overwrite and output traversal are refused. It verifies optional `sources[].sha256`. A batch failure can leave earlier completed clips. No recipe or supplied audio is committed automatically. `node ewesound-audio.mjs ffmpeg` checks the dependency. ## Product protection EweSound is proprietary software. Use these documented operations. Do not reverse engineer, decompile, reconstruct, clone, crack or bypass protections. Owner-authorized source development, debugging and maintenance are permitted. ## Editing rules and command reference Read `guide` and `get_state` first. Preserve existing work. Times are **seconds**, sample indices and tab/history indices are zero-based. Commands run serially; one editing command produces one undo step. Finish recording and close any dialog before issuing editing commands. Microphone recording is controlled by the user in the app. | Tool | Arguments and behavior | | --- | --- | | `guide` | Full copy of this guide. | | `get_state` | Tabs (name, dirty, rate, channels, samples, seconds, bit depth), active tab index, selection, peak, clipboard, history and transport state. | | `new_sound` | Optional `name`, `sample_rate` (8000–192000, default 44100), `channels` (1–8, default 2). Adds an empty tab. | | `open_sound` | Absolute `path`. Adds a new tab; retains existing tabs. Supports WAV, MP3, OGG/OGA, Opus, FLAC, M4A, AAC, WebM as available in WebView. Opens without a GUI save destination, so Save asks where. | | `import_sound` | Absolute `path`. Replaces selection or inserts at cursor, converted to the active sound's rate and channels. | | `save_sound` | Absolute `.wav` `path`; optional `bit_depth` (16, 24, 32 float; defaults to the tab's setting), `overwrite` (default false). Writes a copy atomically. | | `activate_sound` | `index` from `get_state.sounds`. | | `select` | `start`, optional `end` (defaults to start), or `all:true`. Range must fit the sound. | | `generate` | Required `seconds` (0.001–300); optional `kind` (tone/silence), `waveform` (sine/square/sawtooth/triangle), `frequency` (1–Nyquist, default 440), `amplitude` (0–1, default 0.8). Replaces selection or inserts at cursor. | | `effect` | `action`: amplify, normalize, fadeIn, fadeOut, reverse, silence. Amplify requires `db` (−60–60); normalize accepts `db` (−60–0, default −1). Applies to selection, or the entire sound if selection is empty. | | `edit` | `action`: cut, copy, paste, delete, trim. All except paste require a selection. Clipboard works across tabs. | | `channels` | `count` (1–8). Converts the whole sound using the editor mixer. | | `history` | `action`: list (default), undo, redo, jump; jump requires `index`. | | `view` | `action`: fit, selection, in, out. | | `compare_waveforms` | Required boolean `enabled`; optional `reference_sound` (another tab index), `play_active` and `play_reference` (booleans for the left playback checkboxes). Shows two stacked waveforms with synchronized zoom/scroll and a shared time scale. `get_state.comparison` reports enabled, reference_sound, playback_sounds, start and seconds_per_pixel. Checked sounds play aligned at time zero, averaged for headroom; selection limits playback. Does not edit or save audio. | | `transport` | `action`: play, pause, stop. Playback only. | | `agent_control` | Boolean `enabled`. Enables/disables the local HTTP endpoint for this session. | | `analyze_sound` | Optional `start`, `end`, `threshold`, `bins` (0..4096). Read-only sample measurements and waveform data. | | `prepare_clip` | Cut, format, level and fade options described above. Creates a new unsaved tab; preserves source. | | `ffmpeg_info` | External executable path, version, licence and replacement status. No arguments. | The exact JSON schemas are in `src-tauri/agent/tools.json` in source, `tools.json` beside the installed executable, and MCP `tools/list`. Unknown tools and invalid arguments fail without intentionally applying edits. **Save copies:** `save_sound` retains the tab's dirty state, name and GUI save destination. It never marks unsaved work as saved. New/Open retain all existing tabs. Existing output files require explicit `overwrite:true`; failed writes keep the previous file intact. Desktop file operations live in `src-tauri/src/sounds.rs`; explicit automation paths choose only that operation's input/output, without approving future GUI writes. **Selection:** after generation/import/paste, the inserted audio is selected. Before appending, call `select` with `start` equal to the current duration and omit `end`. Otherwise the next insertion replaces that selection. **Limits:** inputs and encoded WAV copies are limited to 64 MiB; decoded automation sounds are limited to 128 MiB across channels. Generation is limited to 300 seconds per call. History remains bounded by the editor's normal memory policy. Long audio can use the ordinary desktop file workflow.