From 2156e75dd645b4257c5901b006a0fbbb440935bb Mon Sep 17 00:00:00 2001
From: Bouke van der Bijl <i@bou.ke>
Date: Fri, 31 Jul 2026 22:34:41 +0200
Subject: [PATCH] Add OpenAPI definition of the Playback server (#5546)

Co-authored-by: aler9 <46489434+aler9@users.noreply.github.com>
---
 api/playback.openapi.yaml | 150 ++++++++++++++++++++++++++++++++++++++
 scripts/lint.mk           |   2 +-
 2 files changed, 151 insertions(+), 1 deletion(-)
 create mode 100644 api/playback.openapi.yaml

diff --git a/api/playback.openapi.yaml b/api/playback.openapi.yaml
new file mode 100644
index 00000000..7e48a96a
--- /dev/null
+++ b/api/playback.openapi.yaml
@@ -0,0 +1,150 @@
+openapi: 3.0.0
+
+info:
+  version: 1.0.0
+  title: MediaMTX Playback API
+  description: Playback API of MediaMTX, used to list and retrieve recorded time spans.
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: http://localhost:9996
+
+security: []
+
+components:
+  schemas:
+    Error:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [error]
+        error:
+          type: string
+
+    ListEntry:
+      type: object
+      properties:
+        start:
+          type: string
+          format: date-time
+        duration:
+          type: number
+          format: double
+        url:
+          type: string
+
+paths:
+  /list:
+    get:
+      operationId: listSegments
+      summary: List recorded time spans for a path.
+      parameters:
+        - name: path
+          in: query
+          required: true
+          description: Path name.
+          schema:
+            type: string
+        - name: start
+          in: query
+          description: Return recordings that start at or after this time.
+          schema:
+            type: string
+            format: date-time
+        - name: end
+          in: query
+          description: Return recordings that end at or before this time.
+          schema:
+            type: string
+            format: date-time
+      responses:
+        "200":
+          description: Recorded time spans found.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ListEntry"
+        "400":
+          description: Invalid request parameters or path configuration.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No recordings found for the requested path and time range.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error while enumerating recordings.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /get:
+    get:
+      operationId: getSegment
+      summary: Download a recording time span as an MP4 file.
+      parameters:
+        - name: path
+          in: query
+          required: true
+          description: Path name.
+          schema:
+            type: string
+        - name: start
+          in: query
+          required: true
+          description: Start time of the requested recording time span.
+          schema:
+            type: string
+            format: date-time
+        - name: duration
+          in: query
+          required: true
+          description: >-
+            Maximum duration of the returned recording, in seconds. The server
+            also accepts the deprecated Go duration format, for example `1m30s`.
+          schema:
+            type: string
+            example: "200.5"
+        - name: format
+          in: query
+          description: Output container format.
+          schema:
+            type: string
+            enum: [fmp4, mp4]
+            default: fmp4
+      responses:
+        "200":
+          description: Recording time span returned as an MP4-compatible file.
+          headers:
+            Accept-Ranges:
+              schema:
+                type: string
+                enum: [none]
+              description: The playback server does not support byte-range requests.
+          content:
+            video/mp4:
+              schema:
+                type: string
+                format: binary
+        "400":
+          description: Invalid request parameters, format, or path configuration.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No recordings found for the requested path and time range.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
diff --git a/scripts/lint.mk b/scripts/lint.mk
index b548b343..738e33fb 100644
--- a/scripts/lint.mk
+++ b/scripts/lint.mk
@@ -25,7 +25,7 @@ lint-apidocs:
 	go run ./internal/apidocsgen --check
 	echo "$$DOCKERFILE_APIDOCS_LINT" | docker build . -f - -t temp
 	docker run --rm -v "$(shell pwd)/api:/s" -w /s temp \
-	sh -c "openapi lint openapi.yaml"
+	sh -c "openapi lint openapi.yaml && openapi lint playback.openapi.yaml"
 
 lint-other:
 	echo "$$DOCKERFILE_PRETTIER" | docker build . -f - -t temp