Skip to content

Commit 251ef1c

Browse files
TolriqTolriq
committed
Add new transcoding extension
New extension to have proper transcoding solution in OpenAPI.
1 parent 00528b1 commit 251ef1c

23 files changed

+884
-0
lines changed

‎content/en/docs/Endpoints/getTranscodeDecision.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: "getTranscodeDecision"
3+
linkTitle: "getTranscodeDecision"
4+
categories:
5+
- Transcoding
6+
description: >
7+
Returns a transcode decision for a given media file.
8+
---
9+
10+
`http://your-server/rest/getTranscodeDecision`
11+
12+
Returns a transcode decision for a given media file. This endpoint is used by clients to determine if a media file should be transcoded before streaming. The server will analyze the provided client information and return a decision.
13+
14+
### Parameters
15+
16+
| Parameter | Req. | OpenS. | Default | Comment |
17+
| --- | --- | --- | --- | --- |
18+
| `songId` | **Yes** | | | The ID of the song to be transcoded. |
19+
20+
### Request Body
21+
22+
The request body must be a JSON object containing the client's capabilities. See the [`ClientInfo`](../payloads/clientinfo) documentation for more details.
23+
24+
{{< tabpane persist=false >}}
25+
{{< tab header="**Example**:" disabled=true />}}
26+
{{< tab header="ClientInfo" lang="json">}}
27+
{
28+
"name": "Pixel 8 Pro",
29+
"platform": "Sonos",
30+
"maxAudioBitrate": 512000,
31+
"maxTranscodingAudioBitrate": 256000,
32+
"directPlayProfiles": [
33+
{
34+
"container": "mp3",
35+
"audioCodec": "mp3",
36+
"protocol": "http",
37+
"maxAudioChannels": 2
38+
},
39+
{
40+
"container": "flac",
41+
"audioCodec": "flac",
42+
"protocol": "*",
43+
"maxAudioChannels": 2
44+
}
45+
,
46+
{
47+
"container": "mp4",
48+
"audioCodec": "flac,aac,alac",
49+
"protocol": "*",
50+
"maxAudioChannels": 2
51+
}
52+
],
53+
"transcodingProfiles": [
54+
{
55+
"container": "mp3",
56+
"audioCodec": "mp3",
57+
"protocol": "http",
58+
"maxAudioChannels": 2
59+
},
60+
{
61+
"container": "flac",
62+
"audioCodec": "flac",
63+
"protocol": "*",
64+
"maxAudioChannels": 2
65+
}
66+
],
67+
"codecProfiles": [
68+
{
69+
"type": "AudioCodec",
70+
"name": "mp3",
71+
"limitations": [
72+
{ "name": "audioBitrate", "comparison": "LessThanEqual", "value": "320000", "required": true }
73+
]
74+
},
75+
{
76+
"type": "AudioCodec",
77+
"name": "flac",
78+
"limitations": [
79+
{ "name": "audioSamplerate", "comparison": "LessThanEqual", "value": "192000", "required": false },
80+
{ "name": "audioChannels", "comparison": "LessThanEqual", "value": "2", "required": false }
81+
]
82+
}
83+
]
84+
}
85+
{{< /tab >}}
86+
{{< /tabpane >}}
87+
88+
### Example
89+
90+
{{< alert color="primary" >}} `http://your-server/rest/getTranscodeDecision.view?songId=123&u=demo&p=demo&v=1.16.1&c=AwesomeClientName&f=json` {{< /alert >}}
91+
92+
### Result
93+
94+
A [`subsonic-response`](../../responses/subsonic-response) element with a nested [`transcodeDecision`](../../responses/transcodedecision) element on success.
95+
96+
{{< tabpane persist=false >}}
97+
{{< tab header="**Example**:" disabled=true />}}
98+
{{< tab header="OpenSubsonic" lang="json">}}
99+
{
100+
"subsonic-response": {
101+
"status": "ok",
102+
"version": "1.16.1",
103+
"type": "AwesomeServerName",
104+
"serverVersion": "0.1.3 (tag)",
105+
"openSubsonic": true,
106+
"transcodeDecision": {
107+
"canDirectPlay": false,
108+
"canTranscode": true,
109+
"transcodeReason": ["AudioCodecNotSupported"],
110+
"errorReason": "",
111+
"transcodeParams": "0001-0005-004",,
112+
"sourceStream": {
113+
"protocol": "http",
114+
"container": "flac",
115+
"codec": "flac",
116+
"audioChannels": 6,
117+
"audioBitrate": 3000000,
118+
"audioProfile": "",
119+
"audioSamplerate": 96000,
120+
"audioBitdepth": 24
121+
},
122+
"transcodeStream": {
123+
"protocol": "hls",
124+
"container": "mp4",
125+
"codec": "aac",
126+
"audioChannels": 2,
127+
"audioBitrate": 256000,
128+
"audioProfile": "xHE-AAC",
129+
"audioSamplerate": 48000,
130+
"audioBitdepth": 16
131+
}
132+
}
133+
}
134+
}
135+
{{< /tab >}}
136+
{{< /tabpane >}}
137+
138+
| Field | Type | Req. | OpenS. | Details |
139+
| --- | --- | --- | --- | --- |
140+
| `transcodeDecision` | [`transcodeDecision`](../../responses/transcodedecision) | **Yes** | | The transcode decision |

‎content/en/docs/Endpoints/getTranscodeStream.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: "getTranscodeStream"
3+
linkTitle: "getTranscodeStream"
4+
categories:
5+
- Transcoding
6+
description: >
7+
Returns a transcoded media stream.
8+
---
9+
10+
`http://your-server/rest/getTranscodeStream`
11+
12+
Returns a transcoded media stream. **Note:** Clients should not try to reconstruct the `transcodeParams`. Instead, they must use the `transcodeParams` provided in the response of the [`getTranscodeDecision`](../gettranscodedecision) endpoint.
13+
14+
### Parameters
15+
16+
| Parameter | Req. | OpenS. | Default | Comment |
17+
| --- | --- | --- | --- | --- |
18+
| `songId` | **Yes** | | | The ID of the track to transcode. |
19+
| `offset` | No | | 0 | The time offset in seconds from which to start transcoding. |
20+
| `transcodeParams` | **Yes** | | | Server-specific transcoding parameters, obtained from the `getTranscodeDecision` endpoint. The value is unique and already properly escaped. |
21+
22+
### Example
23+
24+
{{< alert color="primary" >}} `http://your-server/rest/getTranscodeStream.view?songId=123&offset=0&parameters=...&u=demo&p=demo&v=1.16.1&c=AwesomeClientName&f=json` {{< /alert >}}
25+
26+
### Result
27+
28+
The raw transcoded media stream. In case of an error, a standard HTTP error code is returned with a descriptive message.

‎content/en/docs/Extensions/transcoding.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: "Transcoding"
3+
linkTitle: "Transcoding"
4+
OpenSubsonic:
5+
- Extension
6+
description: >
7+
Adds support for clients to make transcoding decisions and retrieve transcoded media streams.
8+
---
9+
10+
**OpenSubsonic version**: [1](../../opensubsonic-versions)
11+
12+
**OpenSubsonic extension name**: `transcoding` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions))
13+
14+
## Version 1
15+
16+
This extension provides a way for clients to get a server's decision on whether a media file should be transcoded and to retrieve the transcoded stream if necessary.
17+
18+
This extension requires the following endpoints:
19+
20+
- [`getTranscodeDecision`](../../endpoints/gettranscodedecision): Returns a transcode decision for a given media file.
21+
- [`getTranscodeStream`](../../endpoints/gettranscodestream): Returns a transcoded media stream.

‎content/en/docs/Payloads/ClientInfo.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: "ClientInfo"
3+
linkTitle: "ClientInfo [OS]"
4+
opensubsonic:
5+
- Extension
6+
description: >
7+
Contains information about the client's capabilities.
8+
---
9+
10+
{{< tabpane persist=false >}}
11+
{{< tab header="**Example**:" disabled=true />}}
12+
{{< tab header="OpenSubsonic" lang="json">}}
13+
{
14+
"name": "Play:1",
15+
"platform": "Sonos",
16+
"maxAudioBitrate": 512000,
17+
"maxTranscodingAudioBitrate": 256000,
18+
"directPlayProfiles": [
19+
{
20+
"container": "mp3",
21+
"audioCodec": "mp3",
22+
"protocol": "http",
23+
"maxAudioChannels": 2
24+
},
25+
{
26+
"container": "flac",
27+
"audioCodec": "flac",
28+
"protocol": "*",
29+
"maxAudioChannels": 2
30+
}
31+
,
32+
{
33+
"container": "mp4",
34+
"audioCodec": "flac,aac,alac",
35+
"protocol": "*",
36+
"maxAudioChannels": 2
37+
}
38+
],
39+
"transcodingProfiles": [
40+
{
41+
"container": "mp3",
42+
"audioCodec": "mp3",
43+
"protocol": "http",
44+
"maxAudioChannels": 2
45+
},
46+
{
47+
"container": "flac",
48+
"audioCodec": "flac",
49+
"protocol": "*",
50+
"maxAudioChannels": 2
51+
}
52+
],
53+
"codecProfiles": [
54+
{
55+
"type": "AudioCodec",
56+
"name": "mp3",
57+
"limitations": [
58+
{ "name": "audioBitrate", "comparison": "LessThanEqual", "value": "320000", "required": true }
59+
]
60+
},
61+
{
62+
"type": "AudioCodec",
63+
"name": "flac",
64+
"limitations": [
65+
{ "name": "audioSamplerate", "comparison": "LessThanEqual", "value": "192000", "required": false },
66+
{ "name": "audioChannels", "comparison": "LessThanEqual", "value": "2", "required": false }
67+
]
68+
}
69+
]
70+
}
71+
{{< /tab >}}
72+
{{< /tabpane >}}
73+
74+
| Field | Type | Req. | OpenS. | Details |
75+
| --- | --- | --- | --- | --- |
76+
| `name` | string | **Yes** | **Yes** | The name of the client device. |
77+
| `platform` | string | **Yes** | **Yes** | The platform of the client (e.g., Android, iOS). |
78+
| `maxAudioBitrate` | integer | No | **Yes** | The maximum audio bitrate the client can handle. 0 or missing means no limitation. |
79+
| `maxTranscodingAudioBitrate` | integer | No | **Yes** | The maximum audio bitrate for transcoded content. 0 or missing means no limitation. |
80+
| `directPlayProfiles` | [DirectPlayProfile[]](../payloads/directplayprofile) | No | **Yes** | A list of profiles for direct playback. |
81+
| `transcodingProfiles` | [TranscodingProfile[]](../payloads/transcodingprofile) | No | **Yes** | A list of profiles for transcoding. The server should evaluate these in the order they are listed, as a priority list. |
82+
| `codecProfiles` | [CodecProfile[]](../payloads/codecprofile) | No | **Yes** | A list of codec-specific profiles. |

‎content/en/docs/Payloads/CodecProfile.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: "CodecProfile"
3+
linkTitle: "CodecProfile [OS]"
4+
opensubsonic:
5+
- Extension
6+
description: >
7+
Defines a codec profile with optional limitations.
8+
---
9+
10+
{{< tabpane persist=false >}}
11+
{{< tab header="**Example**:" disabled=true />}}
12+
{{< tab header="OpenSubsonic" lang="json">}}
13+
{
14+
"type": "AudioCodec",
15+
"name": "mp3",
16+
"limitations": [
17+
{ "name": "audioBitrate", "comparison": "LessThanEqual", "value": "320000", "required": true }
18+
]
19+
}
20+
{{< /tab >}}
21+
{{< /tabpane >}}
22+
23+
| Field | Type | Req. | OpenS. | Details |
24+
| --- | --- | --- | --- | --- |
25+
| `type` | string | **Yes** | **Yes** | The type of codec profile. Currently only `AudioCodec` is supported. |
26+
| `name` | string | **Yes** | **Yes** | The name of the codec (e.g., mp3, flac). Only a single value is accepted. |
27+
| `limitations` | [Limitation[]](../payloads/limitation) | No | **Yes** | A list of limitations for this codec. |

‎content/en/docs/Payloads/DirectPlayProfile.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: "DirectPlayProfile"
3+
linkTitle: "DirectPlayProfile [OS]"
4+
opensubsonic:
5+
- Extension
6+
description: >
7+
Defines a direct play profile.
8+
---
9+
10+
{{< tabpane persist=false >}}
11+
{{< tab header="**Example**:" disabled=true />}}
12+
{{< tab header="OpenSubsonic" lang="json">}}
13+
{
14+
"container": "mp3",
15+
"audioCodec": "mp3",
16+
"protocol": "http",
17+
"maxAudioChannels": 2
18+
}
19+
{{< /tab >}}
20+
{{< /tabpane >}}
21+
22+
| Field | Type | Req. | OpenS. | Details |
23+
| --- | --- | --- | --- | --- |
24+
| `container` | string | **Yes** | **Yes** | Comma-separated list of supported container format (e.g., mp3, flac, mp4) or `*` to not limit to a specific container. |
25+
| `audioCodec` | string | **Yes** | **Yes** | Comma-separated list of supported audio codecs or `*` to not limit to specific codecs. |
26+
| `protocol` | string | **Yes** | **Yes** | The streaming protocol. Can be `http`, `hls` or `*`. |
27+
| `maxAudioChannels` | integer | No | **Yes** | The maximum number of audio channels supported. |

‎content/en/docs/Payloads/Limitation.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: "Limitation"
3+
linkTitle: "Limitation [OS]"
4+
opensubsonic:
5+
- Extension
6+
description: >
7+
Defines a limitation for a codec profile.
8+
---
9+
10+
{{< tabpane persist=false >}}
11+
{{< tab header="**Example**:" disabled=true />}}
12+
{{< tab header="OpenSubsonic" lang="json">}}
13+
{
14+
"name": "audioBitrate",
15+
"comparison": "LessThanEqual",
16+
"value": "320000",
17+
"required": true
18+
}
19+
{{< /tab >}}
20+
{{< /tabpane >}}
21+
22+
| Field | Type | Req. | OpenS. | Details |
23+
| --- | --- | --- | --- | --- |
24+
| `name` | string | **Yes** | | The name of the limitation. Can be `audioChannels`, `audioBitrate`, `audioProfile`, `audioSamplerate`, or `audioBitdepth`. |
25+
| `comparison` | string | **Yes** | | The comparison operator. Can be `Equals`, `NotEquals`, `LessThanEqual`, `GreaterThanEqual`, `EqualsAny`, or `NotEqualsAny`. |
26+
| `value` | string | **Yes** | | The value to compare against. For `EqualsAny` and `NotEqualsAny`, this should be a pipe-separated (`\|`) list of values (e.g., `44100\|48000`). |
27+
| `required` | boolean | **Yes** | | Whether this limitation must be met. |

‎content/en/docs/Payloads/TranscodingProfile.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: "TranscodingProfile"
3+
linkTitle: "TranscodingProfile [OS]"
4+
opensubsonic:
5+
- Extension
6+
description: >
7+
Defines a transcoding profile.
8+
---
9+
10+
{{< tabpane persist=false >}}
11+
{{< tab header="**Example**:" disabled=true />}}
12+
{{< tab header="OpenSubsonic" lang="json">}}
13+
{
14+
"container": "mp3",
15+
"audioCodec": "mp3",
16+
"protocol": "http",
17+
"maxAudioChannels": 2
18+
}
19+
{{< /tab >}}
20+
{{< /tabpane >}}
21+
22+
| Field | Type | Req. | OpenS. | Details |
23+
| --- | --- | --- | --- | --- |
24+
| `container` | string | **Yes** | **Yes** | The container format (e.g., mp3, flac). Only a single explicit value is accepted (No `*`). |
25+
| `audioCodec` | string | **Yes** | **Yes** | The target audio codec for transcoding. Only a single explicit value is accepted (No `*`). |
26+
| `protocol` | string | **Yes** | **Yes** | The streaming protocol. Can be `http` or `hls`. Only a single explicit value is accepted (No `*`). |
27+
| `maxAudioChannels` | integer | No | **Yes** | The maximum number of audio channels for the transcoded stream. |

‎content/en/docs/Payloads/_index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: "Payloads"
3+
linkTitle: "Payloads"
4+
weight: 10
5+
description: >
6+
Payloads documentation.
7+
---

0 commit comments

Comments
 (0)