Local API and integrations

PadVibe serves a small HTTP API on your own machine. Read its state, trigger pads, or have it call your server.

Security. The API has no password, allows requests from any web page (CORS is open) and listens on all network interfaces. Use it on trusted networks only, and close PadVibe when you do not need it.

Base URL

PadVibe listens on port 9696. From the same computer use http://localhost:9696. From another device use the computer's address, shown in Settings → Integrations.

curl http://localhost:9696/state
curl http://localhost:9696/play/0
curl http://localhost:9696/volume/pad/0/0.5
curl http://localhost:9696/stop_all

Endpoints

All endpoints use GET. Indexes are zero-based positions within the active tab. Volumes and positions are numbers from 0 to 1.

Endpoint	What it does
`GET /state`	Full snapshot: global state (timer, master volume and levels, active tab, output device) and every non-background pad.
`GET /levels`	Master levels: `rms_l`, `rms_r`, `peak_l`, `peak_r`.
`GET /timer`	Remaining time of the playing audio: `remaining_seconds`, `formatted_remaining_timer` and an estimated completion time.
`GET /overlay/timer`	A countdown page for OBS Browser Sources. Optional query: `size`, `color`, `bg`, `host`, `port`.
`GET /play/{index}`	Play (or resume) the pad at `index` in the active tab.
`GET /stop/{index}`	Stop that pad.
`GET /stop_all`	Stop every pad.
`GET /volume/master/{0-1}`	Set the master volume.
`GET /volume/pad/{index}/{0-1}`	Set one pad's volume.
`GET /volume/fader/{index}/{0-1}`	Set a mixer fader's volume.
`GET /seek/{index}/{0-1}`	Seek a pad to a position, as a fraction of its length.
`GET /groups`	List the tabs: `id`, `name`, `pad_count`.
`GET /groups/{index}/switch`	Switch to a tab. This stops running sounds.
`GET /faders`	List the mixer faders.
`GET /audio/devices`	List audio output devices.
`GET /audio/devices/{id}/select`	Choose the output device.
`GET /midi/devices`	List MIDI input devices.
`GET /midi/devices/{name}/connect`	Connect a MIDI input device.
`GET /midi/refresh`	Rescan MIDI devices.

State example

/state returns a global object and a pads array. Pads marked as background are left out.

{
  "global": {
    "remaining_timer_seconds": 133.0,
    "formatted_remaining_timer": "02:13",
    "master_volume": 1.0,
    "master_volume_levels": { "left": 0.31, "right": 0.29 },
    "active_group": { "index": 0, "id": "default", "name": "Podcast" },
    "audio_device": { "id": 0, "name": "Studio Monitors" }
  },
  "pads": [
    {
      "id": 4,
      "name": "Rimshot",
      "keyboard_shortcut": null,
      "settings": { "is_looping": false },
      "playback": { "state": "playing", "position_seconds": 1.2,
                    "duration_seconds": 3.4, "progress_percent": 0.35 }
    }
  ]
}

Playback state is one of empty, stopped, playing or paused.

Webhook

In Settings → Integrations, enter a URL. PadVibe then sends the same JSON as /state to it with an HTTP POST about once a second. Leave it empty to turn the webhook off.

Timer over WebSocket

Connect to ws://localhost:9697 to receive the countdown twice a second:

{"remaining_seconds": 133.0, "formatted": "02:13"}

Show the countdown in OBS

Add a Browser Source and use this URL. Adjust the look with query parameters.

http://localhost:9696/overlay/timer?size=120&color=ffffff&bg=transparent

Under the hood

PadVibe is a Flutter app. Audio and MIDI run in a separate Python process that the app starts and supervises, and the two talk over a local WebSocket. The code is on GitHub. Bug reports and pull requests are welcome.

Build something with it

Found something missing from the API? Open an issue and tell us what you are building.

Download PadVibe Star on GitHub