From 67b832270575de599bc5792503224eec69693b58 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Sat, 21 Mar 2026 02:16:07 +0300
Subject: [PATCH] pinakes-server: add utoipa annotations; manage embedded
 subtitle data

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I30d4b23f09113628dea245404b0a31bd6a6a6964
---
 crates/pinakes-server/src/dto/subtitles.rs | 39 +++++++++++++++++++---
 1 file changed, 34 insertions(+), 5 deletions(-)

diff --git a/crates/pinakes-server/src/dto/subtitles.rs b/crates/pinakes-server/src/dto/subtitles.rs
index a3203ef..1b79e8a 100644
--- a/crates/pinakes-server/src/dto/subtitles.rs
+++ b/crates/pinakes-server/src/dto/subtitles.rs
@@ -1,14 +1,14 @@
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, utoipa::ToSchema)]
 pub struct SubtitleResponse {
   pub id:          String,
   pub media_id:    String,
   pub language:    Option<String>,
   pub format:      String,
   pub is_embedded: bool,
-  pub track_index: Option<usize>,
+  pub track_index: Option<u32>,
   pub offset_ms:   i64,
   pub created_at:  DateTime<Utc>,
 }
@@ -28,17 +28,46 @@ impl From<pinakes_core::subtitles::Subtitle> for SubtitleResponse {
   }
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
 pub struct AddSubtitleRequest {
   pub language:    Option<String>,
   pub format:      String,
   pub file_path:   Option<String>,
   pub is_embedded: Option<bool>,
-  pub track_index: Option<usize>,
+  pub track_index: Option<u32>,
   pub offset_ms:   Option<i64>,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
 pub struct UpdateSubtitleOffsetRequest {
   pub offset_ms: i64,
 }
+
+/// Information about an embedded subtitle track available for extraction.
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct SubtitleTrackInfoResponse {
+  pub index:    u32,
+  pub language: Option<String>,
+  pub format:   String,
+  pub title:    Option<String>,
+}
+
+impl From<pinakes_core::subtitles::SubtitleTrackInfo>
+  for SubtitleTrackInfoResponse
+{
+  fn from(t: pinakes_core::subtitles::SubtitleTrackInfo) -> Self {
+    Self {
+      index:    t.index,
+      language: t.language,
+      format:   t.format.to_string(),
+      title:    t.title,
+    }
+  }
+}
+
+/// Response for listing subtitles on a media item.
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct SubtitleListResponse {
+  pub subtitles:        Vec<SubtitleResponse>,
+  pub available_tracks: Vec<SubtitleTrackInfoResponse>,
+}