feat(player): HLS session progress polling with media server integration (#209)

mkdir700 · mkdir700 · commit a76e8c2f5dee · 2025-10-15T21:52:18.000+08:00
* feat(player): implement HLS session progress polling with visual feedback

- Add waitForSessionReady to poll session creation progress before playback
- Integrate useSessionProgress hook for reusable progress tracking logic
- Display deterministic progress bar with percentage and stage information during session initialization
- Add SessionService.getSessionProgress API with HTTP 425 handling for in-progress state
- Update backend submodule to v64aaf0b with HLS session progress support
- Remove excessive debug logging in SubtitleOverlay to reduce console noise

Changes:

PlayerPage:
- Add waitForSessionReady state and sessionProgress state for UI rendering
- Implement polling loop with 2s interval to fetch session progress until ready
- Display progress bar with stage text and percentage during session creation
- Handle HTTP 425 (session not ready) gracefully in progress polling
- Fallback to default playlist URL if progress response URL parsing fails

useSessionProgress Hook:
- Provide reusable session progress polling with configurable interval (default 2s)
- Auto-stop polling when session is ready or error occurs
- Expose startPolling, stopPolling, reset methods for lifecycle control
- Implement progress threshold (5%) to reduce log noise

SessionService:
- Add getSessionProgress(sessionId) API to fetch session creation progress
- Define SessionProgressResponse and AudioProgressInfo interfaces
- Treat HTTP 425 as normal in-progress state (not error)

This enhancement provides real-time visual feedback during HLS session
initialization, improving user experience by showing progress instead of
generic "loading..." spinner. The polling mechanism ensures playback starts
only after the session is fully ready, preventing premature playlist access.

* refactor(PlayerPage): replace progress bar hardcoded values with theme tokens

- Import theme constants (SPACING, FONT_SIZES, ANIMATION_DURATION, etc.)
- Replace hardcoded width (240px) with SPACING.XXL * 5
- Replace hardcoded heights (4px) with COMPONENT_TOKENS.PROGRESS_BAR.TRACK_HEIGHT_HOVER
- Replace hardcoded border-radius (2px) with COMPONENT_TOKENS.PROGRESS_BAR.TRACK_BORDER_RADIUS
- Replace hardcoded font-sizes (16px, 14px) with FONT_SIZES.BASE and FONT_SIZES.SM
- Replace hardcoded transition timing with ANIMATION_DURATION.SLOW and EASING.STANDARD
- Fix: Add setTranscodeStatus('completed') call after HLS session completes

Changes ensure theme consistency, maintainability, and proper status tracking
across components. Progress bar now respects design system tokens for
cross-theme compatibility.
diff --git a/backend b/backend
@@ -1 +1 @@
-Subproject commit 176ca823ac2e6365f0721e43725c633b2d5aa9da
+Subproject commit 64aaf0bd4d1c1d15bd703bbd5ac00c2034bb2e4b
diff --git a/src/renderer/src/pages/player/PlayerPage.tsx b/src/renderer/src/pages/player/PlayerPage.tsx
@@ -4,6 +4,7 @@ import db from '@renderer/databases'
 import {
   CodecCompatibilityChecker,
   type ExtendedErrorType,
+  SessionError,
   SessionService,
   VideoLibraryService
 } from '@renderer/services'
@@ -16,6 +17,13 @@ import { Layout, Tooltip } from 'antd'
 
 const { Content, Sider } = Layout
 import { MediaServerRecommendationPrompt } from '@renderer/components/MediaServerRecommendationPrompt'
+import {
+  ANIMATION_DURATION,
+  COMPONENT_TOKENS,
+  EASING,
+  FONT_SIZES,
+  SPACING
+} from '@renderer/infrastructure/styles/theme'
 import { ArrowLeft, PanelRightClose, PanelRightOpen } from 'lucide-react'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
@@ -95,6 +103,12 @@ function PlayerPage() {
     originalPath?: string
   } | null>(null)
   const [showMediaServerPrompt, setShowMediaServerPrompt] = useState(false)
+  const [waitingForSessionReady, setWaitingForSessionReady] = useState(false)
+  const [sessionProgress, setSessionProgress] = useState<{
+    percent: number
+    stage: string
+    status: string
+  } | null>(null)
   // const { pokeInteraction } = usePlayerUI()
 
   // 保存转码会话 ID 用于清理
@@ -103,8 +117,64 @@ function PlayerPage() {
   // 加载视频数据
   useEffect(() => {
     let cancelled = false
+    const pollIntervalMs = 2000
+
+    const waitForSessionReady = async (sessionId: string) => {
+      while (!cancelled) {
+        try {
+          const progress = await SessionService.getSessionProgress(sessionId)
+          if (cancelled) {
+            break
+          }
+
+          setSessionProgress((prev) => {
+            const stage = progress.progress_stage?.trim() || prev?.stage || '处理中...'
+            const rawPercent =
+              typeof progress.progress_percent === 'number'
+                ? progress.progress_percent
+                : Number(progress.progress_percent)
+            const percent = Number.isFinite(rawPercent) ? rawPercent : (prev?.percent ?? 0)
+            return {
+              percent,
+              stage,
+              status: progress.status
+            }
+          })
+
+          if (progress.is_ready) {
+            setSessionProgress((prev) => ({
+              percent: 100,
+              stage: progress.progress_stage?.trim() || prev?.stage || '就绪',
+              status: progress.status
+            }))
+            return progress
+          }
+        } catch (progressError) {
+          if (
+            progressError instanceof SessionError &&
+            progressError.statusCode &&
+            progressError.statusCode === 425
+          ) {
+            // 会话尚未返回进度，等待下一轮
+          } else {
+            throw progressError
+          }
+        }
+
+        if (cancelled) {
+          break
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
+      }
+
+      throw new Error('会话进度轮询已取消')
+    }
+
     const loadData = async () => {
       setLoading(true)
+      setWaitingForSessionReady(false)
+      setSessionProgress(null)
       if (!videoId) {
         setError('无效的视频 ID')
         setVideoData(null)
@@ -189,36 +259,83 @@ function PlayerPage() {
 
                 // 保存会话 ID 用于后续清理
                 sessionIdRef.current = sessionResult.session_id
-
-                // 构建完整的播放列表 URL
-                const playListUrl = await SessionService.getPlaylistUrl(sessionResult.session_id)
-
-                // 更新转码信息和播放源
-                usePlayerStore.getState().updateTranscodeInfo({
-                  hlsSrc: playListUrl,
-                  windowId: 0, // 会话模式不再使用 windowId
-                  assetHash: sessionResult.asset_hash,
-                  profileHash: sessionResult.profile_hash,
-                  cached: false, // 会话模式由后端管理缓存
-                  sessionId: sessionResult.session_id,
-                  endTime: Date.now()
+                setWaitingForSessionReady(true)
+                setSessionProgress({
+                  percent: 0,
+                  stage: '正在创建转码会话...',
+                  status: 'initializing'
                 })
 
-                // 切换到 HLS 播放模式
-                usePlayerStore.getState().switchToHlsSource(playListUrl, {
-                  windowId: 0,
-                  assetHash: sessionResult.asset_hash,
-                  profileHash: sessionResult.profile_hash,
-                  cached: false,
-                  sessionId: sessionResult.session_id
-                })
-
-                finalSrc = playListUrl
-
-                logger.info('预转码流程完成，使用 HLS 播放源', {
-                  originalSrc: fileUrl,
-                  hlsSrc: finalSrc
-                })
+                try {
+                  const readyProgress = await waitForSessionReady(sessionResult.session_id)
+
+                  if (cancelled) {
+                    return
+                  }
+
+                  const fallbackPlaylistUrl = await SessionService.getPlaylistUrl(
+                    sessionResult.session_id
+                  )
+                  let playListUrl = fallbackPlaylistUrl
+
+                  if (readyProgress.playlist_url) {
+                    try {
+                      playListUrl = new URL(
+                        readyProgress.playlist_url,
+                        fallbackPlaylistUrl
+                      ).toString()
+                    } catch (urlError) {
+                      logger.warn('解析会话进度返回的播放列表 URL 失败，将使用默认值', {
+                        sessionId: sessionResult.session_id,
+                        playlistUrl: readyProgress.playlist_url,
+                        error: urlError instanceof Error ? urlError.message : String(urlError)
+                      })
+                      playListUrl = fallbackPlaylistUrl
+                    }
+                  }
+
+                  // 更新转码信息和播放源
+                  usePlayerStore.getState().updateTranscodeInfo({
+                    hlsSrc: playListUrl,
+                    windowId: 0, // 会话模式不再使用 windowId
+                    assetHash: sessionResult.asset_hash,
+                    profileHash: sessionResult.profile_hash,
+                    cached: false, // 会话模式由后端管理缓存
+                    sessionId: sessionResult.session_id,
+                    endTime: Date.now()
+                  })
+
+                  // 切换到 HLS 播放模式
+                  usePlayerStore.getState().switchToHlsSource(playListUrl, {
+                    windowId: 0,
+                    assetHash: sessionResult.asset_hash,
+                    profileHash: sessionResult.profile_hash,
+                    cached: false,
+                    sessionId: sessionResult.session_id
+                  })
+                  if (!cancelled) {
+                    usePlayerStore.getState().setTranscodeStatus('completed')
+                  }
+
+                  finalSrc = playListUrl
+
+                  logger.info('预转码流程完成，使用 HLS 播放源', {
+                    originalSrc: fileUrl,
+                    hlsSrc: finalSrc
+                  })
+                } catch (progressError) {
+                  if (!cancelled) {
+                    const message =
+                      progressError instanceof Error ? progressError.message : '获取会话进度失败'
+                    logger.error('会话进度轮询失败，转码流程终止', {
+                      error: message,
+                      sessionId: sessionResult.session_id
+                    })
+                    setError(message || '获取会话进度失败')
+                    usePlayerStore.getState().setTranscodeStatus('failed')
+                  }
+                  return
+                }
               }
             } catch (checkError) {
               logger.error('检查 Media Server 状态失败，显示推荐安装弹窗', {
@@ -270,7 +387,10 @@ function PlayerPage() {
         logger.error(`加载视频数据失败: ${err}`)
         setError(err instanceof Error ? err.message : '加载失败')
       } finally {
-        if (!cancelled) setLoading(false)
+        if (!cancelled) {
+          setWaitingForSessionReady(false)
+          setLoading(false)
+        }
       }
     }
 
@@ -415,13 +535,29 @@ function PlayerPage() {
   }, [handleToggleFullscreen])
 
   if (loading) {
+    const progressPercent = Math.max(0, Math.min(100, Math.round(sessionProgress?.percent ?? 0)))
+
     return (
       <Container>
         <LoadingContainer>
-          <LoadingText>加载中...</LoadingText>
-          <LoadingBarContainer>
-            <LoadingBarProgress />
-          </LoadingBarContainer>
+          {waitingForSessionReady ? (
+            <>
+              <ProgressStageText>
+                {sessionProgress?.stage || '正在创建转码会话...'}
+              </ProgressStageText>
+              <DeterminateBarTrack>
+                <DeterminateBarFill $percent={progressPercent} />
+              </DeterminateBarTrack>
+              <ProgressPercentText>{progressPercent}%</ProgressPercentText>
+            </>
+          ) : (
+            <>
+              <LoadingText>加载中...</LoadingText>
+              <LoadingBarContainer>
+                <LoadingBarProgress />
+              </LoadingBarContainer>
+            </>
+          )}
         </LoadingContainer>
       </Container>
     )
@@ -609,6 +745,35 @@ const LoadingBarProgress = styled.div`
   }
 `
 
+const DETERMINATE_BAR_WIDTH = SPACING.XXL * 5
+
+const DeterminateBarTrack = styled.div`
+  width: ${DETERMINATE_BAR_WIDTH}px;
+  height: ${COMPONENT_TOKENS.PROGRESS_BAR.TRACK_HEIGHT_HOVER}px;
+  background: var(--ant-color-fill-quaternary, rgba(255, 255, 255, 0.08));
+  border-radius: ${COMPONENT_TOKENS.PROGRESS_BAR.TRACK_BORDER_RADIUS}px;
+  overflow: hidden;
+`
+
+const DeterminateBarFill = styled.div<{ $percent: number }>`
+  height: 100%;
+  width: ${({ $percent }) => `${$percent}%`};
+  background: var(--ant-color-primary, #1677ff);
+  border-radius: ${COMPONENT_TOKENS.PROGRESS_BAR.TRACK_BORDER_RADIUS}px;
+  transition: width ${ANIMATION_DURATION.SLOW} ${EASING.STANDARD};
+`
+
+const ProgressStageText = styled.div`
+  font-size: ${FONT_SIZES.BASE}px;
+  color: var(--color-text-1, #ddd);
+  text-align: center;
+`
+
+const ProgressPercentText = styled.div`
+  font-size: ${FONT_SIZES.SM}px;
+  color: var(--color-text-2, #bbb);
+`
+
 const ErrorContainer = styled.div`
   display: flex;
   flex-direction: column;
diff --git a/src/renderer/src/pages/player/components/SubtitleOverlay.tsx b/src/renderer/src/pages/player/components/SubtitleOverlay.tsx
@@ -423,15 +423,6 @@ export const SubtitleOverlay = memo(function SubtitleOverlay({
     return null
   }
 
-  logger.debug('渲染 SubtitleOverlay', {
-    displayMode,
-    position,
-    size,
-    isDragging,
-    isResizing,
-    showBoundaries
-  })
-
   return (
     <OverlayContainer
       ref={overlayRef}
diff --git a/src/renderer/src/services/SessionService.ts b/src/renderer/src/services/SessionService.ts
@@ -105,6 +105,33 @@ export interface SessionDeleteResponse {
   session_id: string
 }
 
+/**
+ * 音频进度信息
+ */
+export interface AudioProgressInfo {
+  status: string
+  progress_percent: number
+  processed_time: number
+  total_duration: number
+  transcode_speed: number
+  eta_seconds: number
+  error_message: string | null
+}
+
+/**
+ * 会话进度响应
+ */
+export interface SessionProgressResponse {
+  session_id: string
+  status: string
+  progress_percent: number
+  progress_stage: string
+  error_message: string | null
+  is_ready: boolean
+  playlist_url: string | null
+  audio_progress: AudioProgressInfo | null
+}
+
 /**
  * 会话错误类型
  */
@@ -518,6 +545,42 @@ export class SessionService {
     }
   }
 
+  /**
+   * 获取会话创建进度
+   *
+   * @param sessionId 会话ID
+   * @returns 会话进度响应
+   */
+  public static async getSessionProgress(sessionId: string): Promise<SessionProgressResponse> {
+    logger.debug('获取会话进度', { sessionId })
+
+    try {
+      const response = await this.makeRequest<SessionProgressResponse>(`/${sessionId}/progress`)
+
+      logger.debug('会话进度获取成功', {
+        sessionId,
+        status: response.status,
+        progress: response.progress_percent,
+        stage: response.progress_stage,
+        isReady: response.is_ready
+      })
+
+      return response
+    } catch (error) {
+      // 如果是 HTTP 425 (Too Early)，这是正常的进行中状态，不记录为错误
+      if (error instanceof SessionError && error.statusCode === 425) {
+        logger.debug('会话尚未就绪 (HTTP 425)', { sessionId })
+        throw error
+      }
+
+      logger.error('获取会话进度失败', {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      throw error
+    }
+  }
+
   /**
    * 获取当前活跃的请求数量（用于监控）
    */
