Add new transcoding extension

content/en/docs/Endpoints/getTranscodeDecision.md

@@ -0,0 +1,140 @@
+---
+title: "getTranscodeDecision"
+linkTitle: "getTranscodeDecision"
+categories:
+- Transcoding
+description: >
+  Returns a transcode decision for a given media file.
+---
+
+`http://your-server/rest/getTranscodeDecision`
+
+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.
+
+### Parameters
+
+| Parameter | Req. | OpenS. | Default | Comment |
+| --- | --- | --- | --- | --- |
+| `songId` | **Yes** | | | The ID of the song to be transcoded. |
+
+### Request Body
+
+The request body must be a JSON object containing the client's capabilities. See the [`ClientInfo`](../payloads/clientinfo) documentation for more details.
+
+{{< tabpane persist=false >}}
+{{< tab header="**Example**:" disabled=true />}}
+{{< tab header="ClientInfo" lang="json">}}
+{
+  "name": "Pixel 8 Pro",
+  "platform": "Sonos",
+  "maxAudioBitrate": 512000,
+  "maxTranscodingAudioBitrate": 256000,
+  "directPlayProfiles": [
+  {
+"container": "mp3",
+"audioCodec": "mp3",
+"protocol": "http",
+"maxAudioChannels": 2
+  },
+  {
+"container": "flac",
+"audioCodec": "flac",
+"protocol": "*",
+"maxAudioChannels": 2
+  }
+  ,
+  {
+"container": "mp4",
+"audioCodec": "flac,aac,alac",
+"protocol": "*",
+"maxAudioChannels": 2
+  }
+  ],
+  "transcodingProfiles": [
+  {
+"container": "mp3",
+"audioCodec": "mp3",
+"protocol": "http",
+"maxAudioChannels": 2
+  },
+  {
+"container": "flac",
+"audioCodec": "flac",
+"protocol": "*",
+"maxAudioChannels": 2
+  }
+  ],
+  "codecProfiles": [
+    {
+      "type": "AudioCodec",
+      "name": "mp3",
+      "limitations": [
+        { "name": "audioBitrate", "comparison": "LessThanEqual", "value": "320000", "required": true }
+      ]
+    },
+    {
+      "type": "AudioCodec",
+      "name": "flac",
+      "limitations": [
+        { "name": "audioSamplerate", "comparison": "LessThanEqual", "value": "192000", "required": false },
+        { "name": "audioChannels",  "comparison": "LessThanEqual", "value": "2",      "required": false }
+      ]
+    }
+  ]
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+### Example
+
+{{< alert color="primary" >}} `http://your-server/rest/getTranscodeDecision.view?songId=123&u=demo&p=demo&v=1.16.1&c=AwesomeClientName&f=json` {{< /alert >}}
+
+### Result
+
+A [`subsonic-response`](../../responses/subsonic-response) element with a nested [`transcodeDecision`](../../responses/transcodedecision) element on success.
+
+{{< tabpane persist=false >}}
+{{< tab header="**Example**:" disabled=true />}}
+{{< tab header="OpenSubsonic" lang="json">}}
+{
+  "subsonic-response": {
+    "status": "ok",
+    "version": "1.16.1",
+    "type": "AwesomeServerName",
+    "serverVersion": "0.1.3 (tag)",
+    "openSubsonic": true,
+    "transcodeDecision": {
+      "canDirectPlay": false,
+      "canTranscode": true,
+      "transcodeReason": ["AudioCodecNotSupported"],
+      "errorReason": "",
+      "transcodeParams": "0001-0005-004",,
+      "sourceStream": {
+        "protocol": "http",
+        "container": "flac",
+        "codec": "flac",
+        "audioChannels": 6,
+        "audioBitrate": 3000000,
+        "audioProfile": "",
+        "audioSamplerate": 96000,
+        "audioBitdepth": 24
+      },
+      "transcodeStream": {
+        "protocol": "hls",
+        "container": "mp4",
+        "codec": "aac",
+        "audioChannels": 2,
+        "audioBitrate": 256000,
+        "audioProfile": "xHE-AAC",
+        "audioSamplerate": 48000,
+        "audioBitdepth": 16
+      }
+    }
+  }
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+| Field |  Type | Req. | OpenS. | Details |
+| --- | --- | --- | --- | --- |
+| `transcodeDecision` | [`transcodeDecision`](../../responses/transcodedecision)  | **Yes** |     | The transcode decision |

content/en/docs/Endpoints/getTranscodeStream.md

@@ -0,0 +1,28 @@
+---
+title: "getTranscodeStream"
+linkTitle: "getTranscodeStream"
+categories:
+- Transcoding
+description: >
+  Returns a transcoded media stream.
+---
+
+`http://your-server/rest/getTranscodeStream`
+
+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.
+
+### Parameters
+
+| Parameter | Req. | OpenS. | Default | Comment |
+| --- | --- | --- | --- | --- |
+| `songId` | **Yes** | | | The ID of the track to transcode. |
+| `offset` | No | | 0 | The time offset in seconds from which to start transcoding. |
+| `transcodeParams` | **Yes** | | | Server-specific transcoding parameters, obtained from the `getTranscodeDecision` endpoint. The value is unique and already properly escaped. |
+
+### Example
+
+{{< 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 >}}
+
+### Result
+
+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

@@ -0,0 +1,21 @@
+---
+title: "Transcoding"
+linkTitle: "Transcoding"
+OpenSubsonic:
+  - Extension
+description: >
+  Adds support for clients to make transcoding decisions and retrieve transcoded media streams.
+---
+
+**OpenSubsonic version**: [1](../../opensubsonic-versions)
+
+**OpenSubsonic extension name**: `transcoding` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions))
+
+## Version 1
+
+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.
+
+This extension requires the following endpoints:
+
+- [`getTranscodeDecision`](../../endpoints/gettranscodedecision): Returns a transcode decision for a given media file.
+- [`getTranscodeStream`](../../endpoints/gettranscodestream): Returns a transcoded media stream.

content/en/docs/Payloads/ClientInfo.md

@@ -0,0 +1,82 @@
+---
+title: "ClientInfo"
+linkTitle: "ClientInfo [OS]"
+opensubsonic:
+- Extension
+description: >
+  Contains information about the client's capabilities.
+---
+
+{{< tabpane persist=false >}}
+{{< tab header="**Example**:" disabled=true />}}
+{{< tab header="OpenSubsonic" lang="json">}}
+{
+  "name": "Play:1",
+  "platform": "Sonos",
+  "maxAudioBitrate": 512000,
+  "maxTranscodingAudioBitrate": 256000,
+  "directPlayProfiles": [
+  {
+"container": "mp3",
+"audioCodec": "mp3",
+"protocol": "http",
+"maxAudioChannels": 2
+  },
+  {
+"container": "flac",
+"audioCodec": "flac",
+"protocol": "*",
+"maxAudioChannels": 2
+  }
+  ,
+  {
+"container": "mp4",
+"audioCodec": "flac,aac,alac",
+"protocol": "*",
+"maxAudioChannels": 2
+  }
+  ],
+  "transcodingProfiles": [
+  {
+"container": "mp3",
+"audioCodec": "mp3",
+"protocol": "http",
+"maxAudioChannels": 2
+  },
+  {
+"container": "flac",
+"audioCodec": "flac",
+"protocol": "*",
+"maxAudioChannels": 2
+  }
+  ],
+  "codecProfiles": [
+    {
+      "type": "AudioCodec",
+      "name": "mp3",
+      "limitations": [
+        { "name": "audioBitrate", "comparison": "LessThanEqual", "value": "320000", "required": true }
+      ]
+    },
+    {
+      "type": "AudioCodec",
+      "name": "flac",
+      "limitations": [
+        { "name": "audioSamplerate", "comparison": "LessThanEqual", "value": "192000", "required": false },
+        { "name": "audioChannels",  "comparison": "LessThanEqual", "value": "2",      "required": false }
+      ]
+    }
+  ]
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+| Field | Type | Req. | OpenS. | Details |
+| --- | --- | --- | --- | --- |
+| `name` | string | **Yes** | **Yes** | The name of the client device. |
+| `platform` | string | **Yes** | **Yes** | The platform of the client (e.g., Android, iOS). |
+| `maxAudioBitrate` | integer | No | **Yes** | The maximum audio bitrate the client can handle. 0 or missing means no limitation. |
+| `maxTranscodingAudioBitrate` | integer | No | **Yes** | The maximum audio bitrate for transcoded content. 0 or missing means no limitation. |
+| `directPlayProfiles` | [DirectPlayProfile[]](../payloads/directplayprofile) | No | **Yes** | A list of profiles for direct playback. |
+| `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. |
+| `codecProfiles` | [CodecProfile[]](../payloads/codecprofile) | No | **Yes** | A list of codec-specific profiles. |

content/en/docs/Payloads/CodecProfile.md

@@ -0,0 +1,27 @@
+---
+title: "CodecProfile"
+linkTitle: "CodecProfile [OS]"
+opensubsonic:
+- Extension
+description: >
+  Defines a codec profile with optional limitations.
+---
+
+{{< tabpane persist=false >}}
+{{< tab header="**Example**:" disabled=true />}}
+{{< tab header="OpenSubsonic" lang="json">}}
+{
+  "type": "AudioCodec",
+  "name": "mp3",
+  "limitations": [
+    { "name": "audioBitrate", "comparison": "LessThanEqual", "value": "320000", "required": true }
+  ]
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+| Field | Type | Req. | OpenS. | Details |
+| --- | --- | --- | --- | --- |
+| `type` | string | **Yes** | **Yes** | The type of codec profile. Currently only `AudioCodec` is supported. |
+| `name` | string | **Yes** | **Yes** | The name of the codec (e.g., mp3, flac). Only a single value is accepted. |
+| `limitations` | [Limitation[]](../payloads/limitation) | No | **Yes** | A list of limitations for this codec. |

content/en/docs/Payloads/DirectPlayProfile.md

@@ -0,0 +1,27 @@
+---
+title: "DirectPlayProfile"
+linkTitle: "DirectPlayProfile [OS]"
+opensubsonic:
+- Extension
+description: >
+  Defines a direct play profile.
+---
+
+{{< tabpane persist=false >}}
+{{< tab header="**Example**:" disabled=true />}}
+{{< tab header="OpenSubsonic" lang="json">}}
+{
+  "container": "mp3",
+  "audioCodec": "mp3",
+  "protocol": "http",
+  "maxAudioChannels": 2
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+| Field | Type | Req. | OpenS. | Details |
+| --- | --- | --- | --- | --- |
+| `container` | string | **Yes** | **Yes** | Comma-separated list of supported container format (e.g., mp3, flac, mp4) or `*` to not limit to a specific container. |
+| `audioCodec` | string | **Yes** | **Yes** | Comma-separated list of supported audio codecs or `*` to not limit to specific codecs. |
+| `protocol` | string | **Yes** | **Yes** | The streaming protocol. Can be `http`, `hls` or `*`. |
+| `maxAudioChannels` | integer | No | **Yes** | The maximum number of audio channels supported. |

content/en/docs/Payloads/Limitation.md

@@ -0,0 +1,27 @@
+---
+title: "Limitation"
+linkTitle: "Limitation [OS]"
+opensubsonic:
+- Extension
+description: >
+  Defines a limitation for a codec profile.
+---
+
+{{< tabpane persist=false >}}
+{{< tab header="**Example**:" disabled=true />}}
+{{< tab header="OpenSubsonic" lang="json">}}
+{
+  "name": "audioBitrate",
+  "comparison": "LessThanEqual",
+  "value": "320000",
+  "required": true
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+| Field | Type | Req. | OpenS. | Details |
+| --- | --- | --- | --- | --- |
+| `name` | string | **Yes** | | The name of the limitation. Can be `audioChannels`, `audioBitrate`, `audioProfile`, `audioSamplerate`, or `audioBitdepth`. |
+| `comparison` | string | **Yes** | | The comparison operator. Can be `Equals`, `NotEquals`, `LessThanEqual`, `GreaterThanEqual`, `EqualsAny`, or `NotEqualsAny`. |
+| `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`). |
+| `required` | boolean | **Yes** | | Whether this limitation must be met. |

content/en/docs/Payloads/TranscodingProfile.md

@@ -0,0 +1,27 @@
+---
+title: "TranscodingProfile"
+linkTitle: "TranscodingProfile [OS]"
+opensubsonic:
+- Extension
+description: >
+  Defines a transcoding profile.
+---
+
+{{< tabpane persist=false >}}
+{{< tab header="**Example**:" disabled=true />}}
+{{< tab header="OpenSubsonic" lang="json">}}
+{
+  "container": "mp3",
+  "audioCodec": "mp3",
+  "protocol": "http",
+  "maxAudioChannels": 2
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+| Field | Type | Req. | OpenS. | Details |
+| --- | --- | --- | --- | --- |
+| `container` | string | **Yes** | **Yes** | The container format (e.g., mp3, flac). Only a single explicit value is accepted (No `*`). |
+| `audioCodec` | string | **Yes** | **Yes** | The target audio codec for transcoding. Only a single explicit value is accepted (No `*`). |
+| `protocol` | string | **Yes** | **Yes** | The streaming protocol. Can be `http` or `hls`. Only a single explicit value is accepted (No `*`). |
+| `maxAudioChannels` | integer | No | **Yes** | The maximum number of audio channels for the transcoded stream. |

content/en/docs/Payloads/_index.md

@@ -0,0 +1,7 @@
+---
+title: "Payloads"
+linkTitle: "Payloads"
+weight: 10
+description: >
+  Payloads documentation.
+---