{ "openapi": "3.1.1", "info": { "title": "Focus Room Playlist Renderer API", "version": "1.0.0", "summary": "Mix a playlist of generated ambience scenes with crossfades and master effects into a WAV.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://focusroomplaylistrender.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Mix a playlist of generated ambience scenes with crossfades and master effects into a WAV.", "description": "Renders a playlist of generated ambience scenes — Focus Room presets such as brown noise, light rain or a surf-like swell, and the generated Soundscape Atlas worlds — one after another with equal-power crossfades, then runs the master effects: low cut, high cut, an 8-band graphic EQ, room reverb, stereo width, volume and a gentle soft limiter. Paste scene lines or a whole Focus Room (JSON or share link). The result is a 16-bit stereo WAV file with a timeline of the scenes and the EQ curve; the Focus Room app uses the same renderer, so both give identical files.\n\nMethodology:\n- Each scene is a Soundscape Atlas scene rendered by the shared audio engine exactly like a Soundscape WAV export: seamless loops of the noise and ambience generators (seeded), layer gains, equal-power pan, filters, slow automation curves and the scene’s own room. Layer fade-outs are switched off, as in live playback.\n- Scenes follow each other on one timeline; scene n + 1 starts one crossfade before scene n ends (at most half of the shorter scene). The overlap uses equal-power gains — outgoing cos(uπ/2), incoming sin(uπ/2) — so the summed power of two unrelated ambiences stays constant. The last scene fades out the same way.\n- Master chain in this order: high-pass (low cut) and low-pass (high cut), both 12 dB/octave Butterworth biquads; eight peaking biquads at the ISO octave centres 63 Hz – 8 kHz with Q 1.41 (Robert Bristow-Johnson’s Audio EQ Cookbook, the same formulas as the Web Audio BiquadFilterNode); room reverb (Freeverb-style, preset reverberation time, mono input); mid/side stereo width; volume; and a soft limiter (tanh above 80 % of a 0.98 ceiling).\n- The mix is written as 16-bit PCM WAV. The Focus Room app plays the same chain live with Web Audio nodes whose coefficients equal these biquads.\n\nAll sounds are synthesized; names such as “surf-like swell” or “coffee-shop-like murmur” describe what filtered noise imitates, not recordings. This is not a medical or hearing device; keep the volume comfortable.", "tags": [ "apps" ], "x-mcp-tool": "focusroom_playlist_render", "x-owner-app": "focusroom", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FocusroomPlaylistRenderInput" }, "examples": { "example1": { "summary": "Three study scenes, 20 seconds each, warm sound", "value": { "items": "brown-noise 20\nrainy-study-room 20\npink-rain 20", "secondsPerItem": 20, "crossfade": 6, "fx": "warm", "sampleRate": "44100" } }, "example2": { "summary": "The “Ocean floor” room shortened to 15 seconds per scene", "value": { "project": "{\"format\":\"focus-room\",\"version\":1,\"name\":\"Ocean floor\",\"playlist\":{\"items\":[{\"id\":\"I1\",\"name\":\"Submarine\",\"minutes\":25,\"preset\":\"submarine\",\"scene\":null},{\"id\":\"I2\",\"name\":\"Surf-like swell\",\"minutes\":25,\"preset\":\"surf-like-swell\",\"scene\":null},{\"id\":\"I3\",\"name\":\"Cavern drips\",\"minutes\":25,\"preset\":\"cavern-drips\",\"scene\":null}],\"shuffle\":false,\"shuffleSeed\":1,\"repeat\":\"all\",\"crossfadeSeconds\":15},\"fx\":{\"volumeDb\":-3,\"lowCutHz\":180,\"highCutHz\":3500,\"eq\":[0,0,0,1.5,0,-2,0,0],\"room\":\"hall\",\"roomAmount\":1.2,\"width\":0.7,\"limiter\":true},\"visual\":{\"background\":\"caustics\",\"seed\":3,\"theme\":\"auto\",\"speed\":1,\"fps\":30,\"reactive\":false,\"clock\":true,\"clock24\":true},\"timer\":{\"mode\":\"pomodoro\",\"focusMinutes\":25,\"shortBreakMinutes\":5,\"longBreakMinutes\":15,\"longEvery\":4,\"cycles\":4,\"chime\":\"bell\",\"chimeDb\":-12,\"breakDuckDb\":-6},\"sleep\":{\"minutes\":0,\"fadeMinutes\":10}}", "secondsPerItem": 15, "sampleRate": "44100" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FocusroomPlaylistRenderResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "FocusroomPlaylistRenderInput": { "type": "object", "additionalProperties": false, "properties": { "items": { "title": "Scenes (one per line: scene id and seconds)", "description": "Generated scenes: brown-noise, pink-rain, surf-like-swell, fireside, forest-stream, night-wind, rainy-study-room, submarine, medieval-tavern, spacecraft-hum, cavern-drips, coffee-shop-murmur. Write \"brown-noise 30\" or \"fireside 2 min\". Used when no room is pasted below.", "type": "string", "maxLength": 2000, "default": "brown-noise 20\nrainy-study-room 20\npink-rain 20" }, "project": { "title": "Focus Room (JSON or share link, optional)", "description": "Paste a .focusroom.json file or a Focus Room share link to render its playlist (shuffle order included) with its master effects. Scenes with Wikimedia Commons recordings cannot be rendered on the server.", "type": "string", "maxLength": 200000, "default": "" }, "secondsPerItem": { "title": "Seconds per scene", "description": "Length of each scene of a pasted room (a room’s scenes usually last many minutes), and of scene lines without their own length.", "type": "number", "minimum": 4, "maximum": 600, "default": 20, "x-unit": "s" }, "crossfade": { "title": "Crossfade", "description": "Equal-power crossfade between scenes (at most half a scene). A pasted room uses its own crossfade.", "type": "number", "minimum": 0, "maximum": 30, "default": 6, "x-unit": "s" }, "fx": { "title": "Master effects preset", "description": "A pasted room uses its own master effects.", "type": "string", "enum": [ "flat", "warm", "bright", "far-away", "small-room" ], "default": "flat" }, "sampleRate": { "title": "Sample rate", "type": "string", "enum": [ "44100", "48000", "22050" ], "default": "44100" } }, "required": [] }, "FocusroomPlaylistRenderResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "seconds", "sampleRate", "channels", "crossfadeSeconds", "scenes", "fx", "peakDb", "rmsDb", "limitedSamples", "wavFile" ], "properties": { "seconds": { "type": "number", "description": "Length of the WAV file (scenes overlap during crossfades)." }, "sampleRate": { "type": "integer" }, "channels": { "type": "integer" }, "crossfadeSeconds": { "type": "number" }, "scenes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "start", "end", "fadeIn", "fadeOut", "origin" ], "properties": { "name": { "type": "string" }, "start": { "type": "number" }, "end": { "type": "number" }, "fadeIn": { "type": "number" }, "fadeOut": { "type": "number" }, "origin": { "type": "string" } } } }, "fx": { "type": "object", "additionalProperties": false, "required": [ "volumeDb", "lowCutHz", "highCutHz", "eq", "room", "roomAmount", "width", "limiter" ], "properties": { "volumeDb": { "type": "number" }, "lowCutHz": { "type": "number" }, "highCutHz": { "type": "number" }, "eq": { "type": "array", "items": { "type": "number" } }, "room": { "type": "string" }, "roomAmount": { "type": "number" }, "width": { "type": "number" }, "limiter": { "type": "boolean" } } }, "peakDb": { "type": "number", "description": "Sample peak in dBFS after the limiter." }, "rmsDb": { "type": "number" }, "limitedSamples": { "type": "integer", "description": "Samples the soft limiter changed (0 = it never engaged)." }, "wavFile": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }