From e45ef785cfb56457dbd7a1dcc959d6ef7ff3675a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=A6=D0=B2=D1=8B=D0=BB=D0=B5=D0=B2=20=D0=90=D0=BB=D0=B5?=
 =?UTF-8?q?=D0=BA=D1=81=D0=B0=D0=BD=D0=B4=D1=80=20=D0=92=D0=B0=D0=B4=D0=B8?=
 =?UTF-8?q?=D0=BC=D0=BE=D0=B2=D0=B8=D1=87?= <Cvylev.A@prezident.ru>
Date: Tue, 28 Jul 2026 21:22:59 +0300
Subject: [PATCH] =?UTF-8?q?feat(player):=20stream=20at=20the=20chosen=20qu?=
 =?UTF-8?q?ality=20+=20per-track=20optimize=20(=C2=A76.6)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Playback quality setting now drives streaming: getStreamUrl appends
?quality= and useAudioPlayer feeds the server-synced streamQuality, so the
backend transcodes on demand (miss → original). Adds an optimizeTrack mutation
and an Optimize action in the metadata editor to warm a track's rendition.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/api/endpoints/library.ts                  | 13 +++++
 src/api/endpoints/streaming.ts                | 12 +++-
 .../metadata-editor/MetadataEditorPage.tsx    | 56 +++++++++++++++++++
 src/hooks/useAudioPlayer.ts                   |  9 ++-
 src/i18n/locales/en.ts                        |  6 ++
 src/i18n/locales/ru.ts                        |  6 ++
 6 files changed, 98 insertions(+), 4 deletions(-)

diff --git a/src/api/endpoints/library.ts b/src/api/endpoints/library.ts
index 164b874..5219f3e 100644
--- a/src/api/endpoints/library.ts
+++ b/src/api/endpoints/library.ts
@@ -201,6 +201,18 @@ export const libraryApi = api.injectEndpoints({
       }),
       invalidatesTags: (_r, _e, trackId) => [{ type: 'Track', id: trackId }],
     }),
+    // Enqueue a transcode to a cached Opus + HLS rendition (§6.6). Fire-and-
+    // forget: the worker does the work, playback keeps using the original.
+    optimizeTrack: build.mutation<
+      { status: string; job_id: string; quality: string },
+      { trackId: string; quality?: string }
+    >({
+      query: ({ trackId, quality = 'high' }) => ({
+        url: `/tracks/${trackId}/optimize`,
+        method: 'POST',
+        params: { quality },
+      }),
+    }),
   }),
   overrideExisting: false,
 });
@@ -219,4 +231,5 @@ export const {
   useLazyGetMetadataMatchesQuery,
   useApplyMetadataMutation,
   useEnrichTrackMutation,
+  useOptimizeTrackMutation,
 } = libraryApi;
diff --git a/src/api/endpoints/streaming.ts b/src/api/endpoints/streaming.ts
index 8a8e9c3..dda7d93 100644
--- a/src/api/endpoints/streaming.ts
+++ b/src/api/endpoints/streaming.ts
@@ -5,9 +5,17 @@ import { getApiBaseUrl } from '../../config/runtime-config';
  * param because `<audio>` can't send an `Authorization` header; the backend
  * accepts `?token=` on `GET /stream/{id}` for exactly this reason.
  */
-export function getStreamUrl(trackId: string, token: string): string {
+export function getStreamUrl(
+  trackId: string,
+  token: string,
+  quality?: string,
+): string {
   const base = getApiBaseUrl();
-  return `${base}/stream/${trackId}?token=${encodeURIComponent(token)}`;
+  const q =
+    quality && quality !== 'original'
+      ? `&quality=${encodeURIComponent(quality)}`
+      : '';
+  return `${base}/stream/${trackId}?token=${encodeURIComponent(token)}${q}`;
 }
 
 export function getCoverUrl(artUrl: string | undefined): string | undefined {
diff --git a/src/features/metadata-editor/MetadataEditorPage.tsx b/src/features/metadata-editor/MetadataEditorPage.tsx
index 108fd33..8115b8d 100644
--- a/src/features/metadata-editor/MetadataEditorPage.tsx
+++ b/src/features/metadata-editor/MetadataEditorPage.tsx
@@ -17,6 +17,7 @@ import {
   useEnrichTrackMutation,
   useGetTrackQuery,
   useLazyGetMetadataMatchesQuery,
+  useOptimizeTrackMutation,
 } from '../../api/endpoints/library';
 import {
   useGetBrokenFilesQuery,
@@ -418,12 +419,67 @@ function SingleTrackEditor() {
               )}
             </div>
           </Card>
+
+          <OptimizeCard trackId={trackId} />
         </div>
       </ScrollArea>
     </div>
   );
 }
 
+/** Enqueue a transcode to a cached Opus + HLS rendition (§6.6 / A6). */
+function OptimizeCard({ trackId }: { trackId: string }) {
+  const { t } = useTranslation();
+  const [optimize, { isLoading, isSuccess, isError }] =
+    useOptimizeTrackMutation();
+
+  return (
+    <Card>
+      <div
+        style={{
+          padding: '1.25rem',
+          display: 'flex',
+          alignItems: 'center',
+          gap: '0.75rem',
+        }}
+      >
+        <div style={{ flex: 1 }}>
+          <div style={{ fontWeight: 600, fontSize: '0.9375rem' }}>
+            {t('metadataEditor.optimize.title')}
+          </div>
+          <div style={{ fontSize: '0.8125rem', color: 'var(--color-text-3)' }}>
+            {t('metadataEditor.optimize.hint')}
+          </div>
+          {isSuccess && (
+            <div style={{ marginTop: '0.5rem' }}>
+              <Callout variant="info">
+                {t('metadataEditor.optimize.enqueued')}
+              </Callout>
+            </div>
+          )}
+          {isError && (
+            <div style={{ marginTop: '0.5rem' }}>
+              <Callout variant="danger">{t('common.error')}</Callout>
+            </div>
+          )}
+        </div>
+        <Button
+          variant="ghost"
+          size="sm"
+          disabled={isLoading}
+          onClick={() => void optimize({ trackId })}
+        >
+          {isLoading ? (
+            <Spinner size="sm" />
+          ) : (
+            t('metadataEditor.optimize.button')
+          )}
+        </Button>
+      </div>
+    </Card>
+  );
+}
+
 function MatchRow({
   match,
   onUse,
diff --git a/src/hooks/useAudioPlayer.ts b/src/hooks/useAudioPlayer.ts
index b88a460..128922c 100644
--- a/src/hooks/useAudioPlayer.ts
+++ b/src/hooks/useAudioPlayer.ts
@@ -10,6 +10,7 @@ import {
 import { nextTrack, prevTrack } from '../store/slices/queue';
 import { play } from '../store/slices/player';
 import { getStreamUrl, getCoverUrl } from '../api/endpoints/streaming';
+import { useGetSettingsQuery } from '../api/endpoints/settings';
 
 let audioElement: HTMLAudioElement | null = null;
 
@@ -26,6 +27,10 @@ export function useAudioPlayer() {
   const player = useAppSelector((s) => s.player);
   const queue = useAppSelector((s) => s.queue);
   const accessToken = useAppSelector((s) => s.auth.accessToken);
+  // Default stream quality (server-synced §A10) → the backend transcodes to it
+  // on demand; a cache miss transparently falls back to the original.
+  const { data: settings } = useGetSettingsQuery();
+  const streamQuality = settings?.streamQuality;
   const isSetup = useRef(false);
   // `ended` is registered once below; read the latest loop flag through a ref
   // so the listener doesn't need to be re-bound on every queue change.
@@ -63,7 +68,7 @@ export function useAudioPlayer() {
   useEffect(() => {
     if (!player.currentTrackId || !accessToken) return;
     const audio = getAudio();
-    const url = getStreamUrl(player.currentTrackId, accessToken);
+    const url = getStreamUrl(player.currentTrackId, accessToken, streamQuality);
     if (audio.src !== url) {
       audio.src = url;
       audio.load();
@@ -73,7 +78,7 @@ export function useAudioPlayer() {
     } else {
       audio.pause();
     }
-  }, [player.currentTrackId, player.isPlaying, accessToken]);
+  }, [player.currentTrackId, player.isPlaying, accessToken, streamQuality]);
 
   useEffect(() => {
     const audio = getAudio();
diff --git a/src/i18n/locales/en.ts b/src/i18n/locales/en.ts
index edd36c7..a476c96 100644
--- a/src/i18n/locales/en.ts
+++ b/src/i18n/locales/en.ts
@@ -628,6 +628,12 @@ const en = {
     error: 'Failed to load track',
     saved: 'Metadata saved.',
     saveError: 'Failed to save metadata.',
+    optimize: {
+      title: 'Optimize format',
+      hint: 'Transcode to a compact Opus + HLS rendition in the background.',
+      button: 'Optimize',
+      enqueued: 'Optimization queued — it runs in the background.',
+    },
     save: 'Save',
     fields: {
       title: 'Title',
diff --git a/src/i18n/locales/ru.ts b/src/i18n/locales/ru.ts
index 1243b0d..97932f1 100644
--- a/src/i18n/locales/ru.ts
+++ b/src/i18n/locales/ru.ts
@@ -627,6 +627,12 @@ const ru: Translations = {
     empty: 'В этой категории пусто.',
   },
   metadataEditor: {
+    optimize: {
+      title: 'Оптимизировать формат',
+      hint: 'Перекодировать в компактный Opus + HLS в фоне.',
+      button: 'Оптимизировать',
+      enqueued: 'Оптимизация поставлена в очередь — выполнится в фоне.',
+    },
     error: 'Не удалось загрузить трек',
     saved: 'Метаданные сохранены.',
     saveError: 'Не удалось сохранить метаданные.',