Routes

The routes below are generated from the OpenAPI document audio-api serves at /v1/audio/openapi.json. The API renders that document from its router table, so this page lists every route the program serves.

The API page is the page beside this one. It says what the API is for, how it chooses a format, how it reads a time span, who may tap a Sink or a Source, and what each error means.

audio.liken.sh capture API, version v1, described in OpenAPI 3.1.1.

Capture audio from a Sink or Source, and stream it as WAV, FLAC, or Ogg Opus.

The path identifies the Sink or Source. The extension or Accept header selects the format. A W3C Media Fragments t= query parameter selects the time span. Authenticate with a client certificate signed by the cluster’s authority, or with a ServiceAccount token for the audio-api audience. A tap requires get on sinks/audio or sources/audio in the audio.liken.sh group. The API stores no audio. Each response streams from the node that hosts the endpoint.

GET /v1/audio

The discovery document. It lists every resource this API serves and gives an RFC 6570 template for each aspect.

Answers

Status Media type Schema Description
200 application/json discovery The discovery document. It lists every resource this API serves and gives an RFC 6570 template for each aspect.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio

The headers of the discovery document. It lists every resource this API serves and gives an RFC 6570 template for each aspect. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Answers

Status Media type Schema Description
200 application/json discovery The discovery document. It lists every resource this API serves and gives an RFC 6570 template for each aspect.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/openapi.json

The OpenAPI 3.1 document for this API.

Answers

Status Media type Schema Description
200 application/openapi+json string (binary) The OpenAPI 3.1 document for this API.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/openapi.json

The headers of the OpenAPI 3.1 document for this API. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Answers

Status Media type Schema Description
200 application/openapi+json string (binary) The OpenAPI 3.1 document for this API.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/openapi.json

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sinks/{name}

The sink format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Media type Schema Description
200 application/json endpoint The sink format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sinks/{name}

The headers of the sink format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Media type Schema Description
200 application/json endpoint The sink format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sinks/{name}

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sinks/{name}/audio

The audio the speakers play now. The Accept header selects the format.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the speakers play now. The Accept header selects the format.
200 audio/ogg; codecs=opus string (binary) The audio the speakers play now. The Accept header selects the format.
200 audio/wav string (binary) The audio the speakers play now. The Accept header selects the format.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Content-Location 200 The extension route that serves the representation the negotiation chose.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sinks/{name}/audio

The headers of the audio the speakers play now. The Accept header selects the format. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the speakers play now. The Accept header selects the format.
200 audio/ogg; codecs=opus string (binary) The audio the speakers play now. The Accept header selects the format.
200 audio/wav string (binary) The audio the speakers play now. The Accept header selects the format.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Content-Location 200 The extension route that serves the representation the negotiation chose.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sinks/{name}/audio

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sinks/{name}/audio.flac

The audio the speakers play now, as FLAC.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the speakers play now, as FLAC.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sinks/{name}/audio.flac

The headers of the audio the speakers play now, as FLAC. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the speakers play now, as FLAC.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sinks/{name}/audio.flac

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sinks/{name}/audio.opus

The audio the speakers play now, as Ogg Opus.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/ogg; codecs=opus string (binary) The audio the speakers play now, as Ogg Opus.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sinks/{name}/audio.opus

The headers of the audio the speakers play now, as Ogg Opus. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/ogg; codecs=opus string (binary) The audio the speakers play now, as Ogg Opus.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sinks/{name}/audio.opus

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sinks/{name}/audio.wav

The audio the speakers play now, as PCM in a RIFF WAVE stream.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/wav string (binary) The audio the speakers play now, as PCM in a RIFF WAVE stream.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sinks/{name}/audio.wav

The headers of the audio the speakers play now, as PCM in a RIFF WAVE stream. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/wav string (binary) The audio the speakers play now, as PCM in a RIFF WAVE stream.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sinks/{name}/audio.wav

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sources/{name}

The source format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Media type Schema Description
200 application/json endpoint The source format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sources/{name}

The headers of the source format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Media type Schema Description
200 application/json endpoint The source format and capture routes. It gives the target node, the rate and channel count for a capture, and the formats the routes serve.
304 none The If-None-Match field matches this document’s ETag.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Cache-Control 200 Always no-cache. A client revalidates with If-None-Match and gets a 304.
ETag 200 The build this API was made from. The router table is compiled in, so the build is the whole of a document’s identity.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sources/{name}

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sources/{name}/audio

The audio the microphone captures now. The Accept header selects the format.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the microphone captures now. The Accept header selects the format.
200 audio/ogg; codecs=opus string (binary) The audio the microphone captures now. The Accept header selects the format.
200 audio/wav string (binary) The audio the microphone captures now. The Accept header selects the format.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Content-Location 200 The extension route that serves the representation the negotiation chose.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sources/{name}/audio

The headers of the audio the microphone captures now. The Accept header selects the format. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the microphone captures now. The Accept header selects the format.
200 audio/ogg; codecs=opus string (binary) The audio the microphone captures now. The Accept header selects the format.
200 audio/wav string (binary) The audio the microphone captures now. The Accept header selects the format.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Content-Location 200 The extension route that serves the representation the negotiation chose.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sources/{name}/audio

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sources/{name}/audio.flac

The audio the microphone captures now, as FLAC.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the microphone captures now, as FLAC.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sources/{name}/audio.flac

The headers of the audio the microphone captures now, as FLAC. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/flac string (binary) The audio the microphone captures now, as FLAC.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sources/{name}/audio.flac

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sources/{name}/audio.opus

The audio the microphone captures now, as Ogg Opus.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/ogg; codecs=opus string (binary) The audio the microphone captures now, as Ogg Opus.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sources/{name}/audio.opus

The headers of the audio the microphone captures now, as Ogg Opus. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.
bitrate query no string The Opus bitrate in kbit/s per channel, 6 to 256. opusenc chooses one from the sample rate when this is absent. A bitrate on WAV or FLAC is a 400.

Answers

Status Media type Schema Description
200 audio/ogg; codecs=opus string (binary) The audio the microphone captures now, as Ogg Opus.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sources/{name}/audio.opus

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

GET /v1/audio/sources/{name}/audio.wav

The audio the microphone captures now, as PCM in a RIFF WAVE stream.

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/wav string (binary) The audio the microphone captures now, as PCM in a RIFF WAVE stream.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

HEAD /v1/audio/sources/{name}/audio.wav

The headers of the audio the microphone captures now, as PCM in a RIFF WAVE stream. HEAD takes no sample and makes no call to the capture container (RFC 9110 section 9.3.2).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.
t query no string The W3C Media Fragments temporal dimension in NPT: t=begin,end, t=begin, or t=,end. The interval is half-open, and its zero is the instant the capture container accepts the request. A begin over 60 seconds is a 400.

Answers

Status Media type Schema Description
200 audio/wav string (binary) The audio the microphone captures now, as PCM in a RIFF WAVE stream.
400 application/problem+json problem A t= the grammar refuses, a t=a,b with a at or after b, a begin over 60 seconds, a repeated dimension, an unknown query parameter, or a knob the format does not take.
401 application/problem+json problem No client certificate and no token, or a token the TokenReview refuses. The WWW-Authenticate header carries the review’s own words.
403 application/problem+json problem The SubjectAccessReview said no. The WWW-Authenticate header names the scope the caller would need.
404 application/problem+json problem No Sink or Source of that name, or PipeWire holds no node for it.
405 application/problem+json problem A method other than GET, HEAD, and OPTIONS.
406 application/problem+json problem Accept excludes every representation the route serves. The acceptable member lists what it does serve, with the URI of each.
409 application/problem+json problem The endpoint has no status.node. The detail says to power the device on.
500 application/problem+json problem The tap’s link landed on a node other than the one asked for.
502 application/problem+json problem The capture container answered something that is not HTTP or not a problem document.
503 application/problem+json problem The capture container is at its tap limit, refused the connection, is not ready, has no certificate this API trusts, or PipeWire refused pw-record.
504 application/problem+json problem The capture container sent no headers within the header timeout.

Headers

Header Status Description
Accept-Ranges 200 Always none. A live capture has no byte identity: offset 44 of two requests is two different moments.
Cache-Control 200 Always no-store. A capture is never cacheable.
Content-Disposition 200 The save name a browser gets, with the RFC 3339 time’s colons replaced by dashes.
Link 200 The service-desc and service-doc relations on every answer, describedby on every route that names an object, alternate on the extensionless route, and related from an info document to its capture routes.
Vary 200 Always Accept. RFC 9110 section 12.5.5’s second purpose: this answer was subject to negotiation, and an Accept could have made it a 406.

OPTIONS /v1/audio/sources/{name}/audio.wav

The methods this route allows, as a 204 with Allow (RFC 9110 section 10.2.1).

Parameters

Parameter In Required Type Description
name path yes string The Sink or Source name. The operator builds this name from the hardware identity.

Answers

Status Description
204 The methods this route allows.

Headers

Header Status Description
Allow 204 GET, HEAD, OPTIONS.

Schemas

discovery

The discovery document the three capture APIs share.

Field Type Required Description
openapi string yes
resources object yes

endpoint

One endpoint’s own document: the node a tap targets, the rate and channel count it would use, the format the node reports now, and the forms served.

Field Type Required Description
channels integer no
connectionType string no
extensions []string yes
format object no
kind string yes
mediaTypes []string yes
name string yes
node string yes
nodeName string no
rate integer no

problem

The RFC 9457 problem document every error answers with. detail carries the source’s own words: pw-record’s stderr, an encoder’s stderr, or the API server’s status message. instance is the request path, a number sign, and the request id the log line carries.

Field Type Required Description
acceptable []object no
detail string no
instance string yes
status integer yes
title string yes
type string (uri) yes

problem.acceptable[]

Field Type Required Description
href string yes
type string yes

Security

Every route requires mutualTLS, or bearerToken, unless its own section states otherwise.

Scheme Type Description
bearerToken HTTP bearer, JWT A ServiceAccount token minted with the audience audio-api, which this API checks with a TokenReview.
mutualTLS Mutual TLS A client certificate the cluster’s own authority signed. The subject’s common name is the user and its organization values are the groups, which is how the API server reads one.

The document itself

audio-api serves the document this page is made from, at /v1/audio/openapi.json on the API’s own host. This site publishes the same copy at /v1/audio/openapi.json , where the servers member is a placeholder: the served copy names the origin the request reached.