Web delivery
Audio as bytes, and the HTTP response that serves it with range requests, ETag and 304.
On this page
Audio as bytes, and the HTTP response that serves it with range requests, ETag and 304.
audioEncode
Turns audio into the bytes of an audio file without touching the disk, for sending in a web response, storing in a database or handing to another service. WAV, MP3 and FLAC need nothing else. OGG, Opus, M4A and AAC need FFmpeg.
audioEncode( audio, format="wav", bitDepth=16, bitrate=0 )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer to encode. |
format | string | "wav" | wav, mp3, flac, ogg, opus, m4a or aac. Defaults to wav. |
bitDepth | integer | 16 | For WAV: 16 or 24 for integer PCM, or 32 for 32 bit float. For FLAC: 16 or 24. Defaults to 16. Ignored for the other formats. |
bitrate | integer | 0 | For MP3, OGG, Opus and AAC: the bitrate in kbps, 0 for the format's default. Ignored for WAV and FLAC. |
Returns The encoded file as binary data.
audioDecode
Reads audio from memory, for example an upload, a database column or the body of an HTTP response. The format is found from the content, so WAV, MP3 and FLAC need no hint. OGG, Opus, M4A, AAC and other containers need FFmpeg.
audioDecode( data, format="" )
| Argument | Type | Default | |
|---|---|---|---|
data | any | required | The bytes of the file, as binary data. |
format | string | "" | Optional: a file name or extension such as upload.ogg, which helps to recognise formats that have no signature. |
Returns An audio buffer.
audioHttpResponse
Works out what to send for a request for audio. It does not send anything: copy the status, the headers and the body to the response of your web server.
It answers what a browser audio player asks for. A request with a Range header gets just those bytes with status 206, which is what lets a player seek without downloading everything. A repeated request with a matching If-None-Match gets 304 and no body. HEAD gets the headers only. A range that is past the end gets 416.
The source can be a path (the file is sent as it is, and only the asked bytes are read from disk), an audio buffer (encoded to the format) or binary data you already encoded with audioEncode(). Encoding is done on every call, so encode once and keep the bytes when many requests ask for the same sound.
audioHttpResponse( source, request, format="", bitrate=0, bitDepth=16, maxAgeSeconds=3600, filename="", download=false )
| Argument | Type | Default | |
|---|---|---|---|
source | any | required | A file path, an audio buffer or binary data. |
request | struct | optional | The request: a struct with method (GET or HEAD, defaults to GET) and headers, a struct of the request headers such as range and if-none-match. A struct that has no headers key is taken to be the headers themselves. |
format | string | "" | wav, mp3, flac, ogg, opus, m4a or aac. For a buffer it is the format to encode (defaults to mp3). For a path, leave it out to send the file as it is, or give another format to convert. For binary data it says what the data is, and is found from the content when left out. |
bitrate | integer | 0 | For MP3, OGG, Opus and AAC when audio is encoded: the bitrate in kbps. Defaults to the format's own. |
bitDepth | integer | 16 | For WAV and FLAC when audio is encoded. Defaults to 16. |
maxAgeSeconds | long | 3600 | How long a browser may keep it without asking again. 0 makes it ask every time (cheap, since the ETag answers 304), a negative number forbids storing it. Defaults to 3600. |
filename | string | "" | A file name offered to a browser that saves the audio. |
download | boolean | false | True to ask the browser to save the file instead of playing it. Defaults to false. |
Returns A struct with status (200, 206, 304, 405 or 416), statusText, headers (a struct) and body (binary data, empty when there is nothing to send).