From 7ef2eed2ad324c06ec249689a784836ada968c07 Mon Sep 17 00:00:00 2001
From: Vito0912 <86927734+Vito0912@users.noreply.github.com>
Date: Tue, 30 Jul 2024 17:24:12 +0200
Subject: [PATCH] Added /api/items/{id}/play endpoint

---
 docs/controllers/LibraryItemController.yaml | 59 +++++++++++++++
 docs/objects/entities/Device.yaml           | 42 +++++++++++
 docs/objects/entities/PlaybackSession.yaml  | 82 +++++++++++++++++++++
 docs/schemas.yaml                           |  3 +
 4 files changed, 186 insertions(+)
 create mode 100644 docs/objects/entities/Device.yaml
 create mode 100644 docs/objects/entities/PlaybackSession.yaml

diff --git a/docs/controllers/LibraryItemController.yaml b/docs/controllers/LibraryItemController.yaml
index 94d495189..60a7699a1 100644
--- a/docs/controllers/LibraryItemController.yaml
+++ b/docs/controllers/LibraryItemController.yaml
@@ -40,3 +40,62 @@ paths:
                       description: TODO
                       oneOf:
                         - $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItem'
+  /api/items/{id}/play:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library item.
+        required: true
+        schema:
+          $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId'
+    post:
+      operationId: playLibraryItem
+      summary: Play a library item.
+      description: Play a library item.
+      tags:
+        - LibraryItem
+      parameters:
+        - in: query
+          name: deviceInfo
+          description: The device information to send to the server.
+          schema:
+              $ref: '../objects/entities/Device.yaml#/components/schemas/deviceInfo'
+        - in: query
+          name: forceDirectPlay
+          description: Whether to force direct play of the library item.
+          schema:
+              type: boolean
+              example: false
+        - in: query
+          name: forceTranscode
+          description: Whether to force transcoding of the library item.
+          schema:
+              type: boolean
+              example: false
+        - in: query
+          name: supportedMimeTypes
+          description: The supported mime types for the device.
+          schema:
+                type: array
+                items:
+                    type: string
+        - in: query
+          name: mediaPlayer
+          description: The media player to use.
+          schema:
+              type: string
+      responses:
+        '200':
+            description: OK
+            content:
+                application/json:
+                  schema:
+                      $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
+        '404':
+            description: Not Found
+            content:
+                text/html:
+                  schema:
+                      type: string
+                      description: The library item does not have any audio tracks to play.
+                      example: Not Found
diff --git a/docs/objects/entities/Device.yaml b/docs/objects/entities/Device.yaml
new file mode 100644
index 000000000..17e99b277
--- /dev/null
+++ b/docs/objects/entities/Device.yaml
@@ -0,0 +1,42 @@
+components:
+  schemas:
+    deviceId:
+      description: The client device identifier.
+      type: string
+      example: 1
+    clientVersion:
+      description: The client version.
+      type: string
+      example: 1.0.0
+    clientName:
+      description: The client name.
+      type: string
+      example: "Audible"
+    manufacturer:
+      description: The manufacturer of the device.
+      type: string
+      example: "Apple"
+    model:
+        description: The model of the device.
+        type: string
+        example: "iPhone 12"
+    sdkVersion:
+      description: For an Android client, the Android SDK version of the client.
+      type: integer
+      example: 49
+    deviceInfo:
+        description: The device information to send to the server.
+        type: object
+        properties:
+            deviceId:
+              $ref: '#/components/schemas/deviceId'
+            clientVersion:
+              $ref: '#/components/schemas/clientVersion'
+            clientName:
+              $ref: '#/components/schemas/clientName'
+            manufacturer:
+              $ref: '#/components/schemas/manufacturer'
+            model:
+              $ref: '#/components/schemas/model'
+            sdkVersion:
+              $ref: '#/components/schemas/sdkVersion'
diff --git a/docs/objects/entities/PlaybackSession.yaml b/docs/objects/entities/PlaybackSession.yaml
new file mode 100644
index 000000000..0867e6d4e
--- /dev/null
+++ b/docs/objects/entities/PlaybackSession.yaml
@@ -0,0 +1,82 @@
+components:
+  schemas:
+    playbackSessionId:
+      description: The playback session identifier.
+      type: string
+      format: uuid
+    playbackSession:
+      id:
+        $ref: '#/components/schemas/playbackSessionId'
+      userId:
+        $ref: './User.yaml#/components/schemas/userId'
+      libraryId:
+        $ref: '../Library.yaml#/components/schemas/libraryId'
+      libraryItemId:
+        $ref: '../LibraryItem.yaml#/components/schemas/libraryItemId'
+      episodeId:
+        $ref: '../mediaTypes/Podcast.yaml#/components/schemas/episodeId'
+        nullable: true
+      mediaType:
+        $ref: '../../controllers/LibraryItemController.yaml#/components/schemas/libraryMediaType'
+      mediaMetadata:
+        description: The metadata of the media.
+        oneOf:
+          - $ref: '../mediaTypes/Book.yaml#/components/schemas/bookMinified'
+          - $ref: '../mediaTypes/Podcast.yaml#/components/schemas/podcastMinified'
+      chapters:
+        description: The chapters of the media.
+        type: array
+        items:
+          $ref: '../metadata/BookMetadata.yaml#/components/schemas/bookChapter'
+      displayTitle:
+        description: The display title of the media.
+        type: string
+      displayAuthor:
+        description: The display author of the media.
+        type: string
+      coverPath:
+        $ref: '../Book.yaml#/components/schemas/bookCoverPath'
+      duration:
+        $ref: '../schemas.yaml#/components/schemas/durationSec'
+      playMethod:
+        type: integer
+        description: The method used to play the media. 0 = Direct play, 1 = Direct Stream, 2 = Transcode, 3 = Local
+      mediaPlayer:
+        type: string
+        description: The media player used to play the media.
+      deviceInfo:
+        $ref: './Device.yaml#/components/schemas/deviceInfo'
+      serverVersion:
+        $ref: '../schemas.yaml#/components/schemas/serverVersion'
+      date:
+        description: TODO
+        type: String
+      dayOfWeek:
+        description: TODO
+        type: String
+      timeListening:
+        $ref: '../schemas.yaml#/components/schemas/durationSec'
+      startTime:
+        $ref: '../schemas.yaml#/components/schemas/durationSec'
+      currentTime:
+        $ref: '../schemas.yaml#/components/schemas/durationSec'
+      createdAt:
+        $ref: '../schemas.yaml#/components/schemas/createdAt'
+      updatedAt:
+        $ref: '../schemas.yaml#/components/schemas/updatedAt'
+    playbackSessionExpanded:
+      description: Expanded playback session schema.
+      allOf:
+        - $ref: '#/components/schemas/playbackSession'
+        - properties:
+            audioTracks:
+              description: The audio tracks of the media.
+              type: array
+              items:
+                  $ref: '../files/AudioTrack.yaml#/components/schemas/AudioTrack'
+            videoTrack:
+              description: The video track of the media. TODO
+              type: object
+              nullable: true
+            libraryItem:
+                $ref: '../LibraryItem.yaml#/components/schemas/libraryItem'
diff --git a/docs/schemas.yaml b/docs/schemas.yaml
index e4e05e809..ee97e3124 100644
--- a/docs/schemas.yaml
+++ b/docs/schemas.yaml
@@ -59,6 +59,9 @@ components:
       type: boolean
       example: true
       default: false
+    serverVersion:
+      type: string
+      description: The server version
     region:
       description: The region used to search.
       type: string