Merge pull request #24 from NuclearPlayer/feat/streaming

Streaming

Author: nukeop

packages/docs/SUMMARY.md

@@ -6,6 +6,7 @@
 * [Plugin system](plugins/plugin-system.md)
 * [Settings](plugins/settings.md)
 * [Queue](plugins/queue.md)
+* [Streaming](plugins/streaming.md)
 * [Providers](plugins/providers.md)
 
 ## Theming

packages/docs/plugins/queue.md

@@ -42,10 +42,6 @@ type QueueItem = {
   status: 'idle' | 'loading' | 'success' | 'error';
   error?: string;            // Error message if status is 'error'
 
-  // Stream resolution tracking
-  activeStreamIndex: number;       // Which stream from track.streams[] is active
-  failedStreamIndices: number[];   // Streams that have been tried and failed
-  
   // Metadata
   addedAtIso: string;        // ISO timestamp of when added
 };

packages/docs/plugins/streaming.md

@@ -0,0 +1,107 @@
+---
+description: Resolve audio streams for tracks in Nuclear's queue.
+---
+
+# Streaming
+
+## Streaming API for Plugins
+
+The Streaming API resolves playable audio URLs for tracks. When a user plays a track, Nuclear searches for stream candidates (e.g., YouTube videos) and then resolves the actual audio URL just-in-time.
+
+{% hint style="info" %}
+Access streaming via `NuclearAPI.Streaming.*` in your plugin's lifecycle hooks.
+{% endhint %}
+
+---
+
+## Core concepts
+
+### Two-phase resolution
+
+Stream resolution happens in two phases:
+
+1. **Candidate discovery** — Search for potential sources (e.g., YouTube videos matching the track)
+2. **Stream resolution** — Extract the actual audio URL from the top candidate
+
+### Stream candidates
+
+A candidate represents a potential audio source before the URL is resolved. Key fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for this candidate |
+| `title` | `string` | Display title (e.g., video title) |
+| `durationMs` | `number?` | Duration in milliseconds |
+| `thumbnail` | `string?` | Preview image URL |
+| `source` | `ProviderRef` | Which streaming provider found this |
+| `stream` | `Stream?` | Resolved audio URL (populated after resolution) |
+| `lastResolvedAtIso` | `string?` | When the stream was last resolved, so we know when to refresh it |
+| `failed` | `boolean` | True if resolution failed permanently |
+
+{% hint style="info" %}
+See `StreamCandidate` in `@nuclearplayer/model` for the full type definition.
+{% endhint %}
+
+### Streams
+
+A resolved stream contains the actual playable URL. Key fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | `string` | The audio URL |
+| `protocol` | `'file' \| 'http' \| 'https' \| 'hls'` | Stream protocol |
+| `mimeType` | `string?` | e.g., `'audio/webm'` |
+| `bitrateKbps` | `number?` | Audio quality |
+| `codec` | `string?` | e.g., `'opus'`, `'aac'` |
+| `qualityLabel` | `string?` | e.g., `'320kbps'`, `'FLAC'` |
+
+{% hint style="info" %}
+See `Stream` in `@nuclearplayer/model` for the full type definition.
+{% endhint %}
+
+### Stream expiry
+
+Audio URLs from services like YouTube typically expire after a period (often as short as a few hours). Nuclear automatically re-resolves expired streams when needed. The expiry window is configurable via the `playback.streamExpiryMs` setting.
+
+---
+
+## Usage
+
+### Finding candidates
+
+Call `resolveCandidatesForTrack(track)` with a `Track` object containing at least a title and artist. The method returns a result object with `success`, `candidates` (on success), or `error` (on failure).
+
+### Resolving a stream
+
+Once we have a candidate, Nuclear calls `resolveStreamForCandidate(candidate)` to get the actual audio URL. The method returns an updated candidate with the `stream` field populated, or the same candidate if already resolved/failed. This happens when we try to play the track.
+
+---
+
+## Reference
+
+| Method | Description |
+|--------|-------------|
+| `resolveCandidatesForTrack(track)` | Search for stream candidates matching a track. Returns `StreamResolutionResult`. |
+| `resolveStreamForCandidate(candidate)` | Resolve the audio URL for a candidate. Returns updated `StreamCandidate` or `undefined`. The candidate is not mutated, a fresh copy is returned. |
+
+### Resolution behavior
+
+| Input state | Output |
+|-------------|--------|
+| Candidate with `failed: true` | Returns candidate unchanged (no retry) |
+| Candidate with valid, non-expired `stream` | Returns candidate unchanged (cached) |
+| Candidate with expired or missing `stream` | Attempts resolution, returns updated candidate |
+| Resolution succeeds | Returns candidate with `stream` populated |
+| Resolution fails after retries | Returns candidate with `failed: true` |
+| No streaming provider registered | Returns `undefined` |
+
+---
+
+## Related settings
+
+These core settings affect stream resolution:
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `playback.streamExpiryMs` | How long before a resolved stream is considered expired | 1 hour |
+| `playback.streamResolutionRetries` | How many times to retry before marking as failed | 3 |

packages/hifi/src/Sound.tsx

@@ -3,6 +3,7 @@ import {
   cloneElement,
   isValidElement,
   ReactNode,
+  ScriptHTMLAttributes,
   useCallback,
   useEffect,
   useMemo,
@@ -21,8 +22,8 @@ export type SoundProps = {
   status: SoundStatus;
   seek?: number;
   crossfadeMs?: number;
-  preload?: 'none' | 'metadata' | 'auto';
-  crossOrigin?: '' | 'anonymous' | 'use-credentials';
+  preload?: HTMLAudioElement['preload'];
+  crossOrigin?: ScriptHTMLAttributes<HTMLAudioElement>['crossOrigin'];
   onTimeUpdate?: (args: { position: number; duration: number }) => void;
   onEnd?: () => void;
   onLoadStart?: () => void;

packages/i18n/src/i18n.ts

@@ -33,6 +33,7 @@ i18n.use(initReactI18next).init({
     'settings',
     'dashboard',
     'plugins',
+    'streaming',
   ],
   interpolation: {
     escapeValue: false,

packages/i18n/src/locales/en_US.json

@@ -123,6 +123,14 @@
       "crossfadeMs": {
         "title": "Crossfade",
         "description": "Crossfade duration between tracks in milliseconds"
+      },
+      "streamExpiryMs": {
+        "title": "Stream expiry time",
+        "description": "How long before a resolved stream URL is considered expired and needs re-resolution"
+      },
+      "streamResolutionRetries": {
+        "title": "Stream resolution retries",
+        "description": "Number of times to retry resolving a stream URL before moving to the next candidate"
       }
     }
   },
@@ -138,5 +146,11 @@
     "error": {
       "prefix": "Error:"
     }
+  },
+  "streaming": {
+    "errors": {
+      "noCandidatesFound": "Failed to find stream candidates",
+      "allCandidatesFailed": "All stream candidates failed"
+    }
   }
 }

packages/model/src/index.ts

@@ -1,3 +1,5 @@
+import type { LocalFileInfo, StreamCandidate } from './streaming';
+
 export type ProviderRef = {
   provider: string;
   id: string;
@@ -52,30 +54,6 @@ export type PlaylistRef = {
   source: ProviderRef;
 };
 
-export type Stream = {
-  url: string;
-  protocol: 'file' | 'http' | 'https' | 'hls';
-  mimeType?: string;
-  bitrateKbps?: number;
-  codec?: string;
-  container?: string;
-  qualityLabel?: string;
-  durationMs?: number;
-  contentLengthBytes?: number;
-  source: ProviderRef;
-};
-
-export type LocalFileInfo = {
-  fileUri: string;
-  fileSize?: number;
-  format?: string;
-  bitrateKbps?: number;
-  sampleRateHz?: number;
-  channels?: number;
-  fingerprint?: string;
-  scannedAtIso?: string;
-};
-
 export type Track = {
   title: string;
   artists: ArtistCredit[];
@@ -87,7 +65,7 @@ export type Track = {
   tags?: string[];
   source: ProviderRef;
   localFile?: LocalFileInfo;
-  streams?: Stream[];
+  streamCandidates?: StreamCandidate[];
 };
 
 export type Album = {
@@ -135,3 +113,4 @@ export type PlaylistItem = {
 export { pickArtwork } from './artwork';
 export type { QueueItem, RepeatMode, Queue } from './queue';
 export type { SearchCategory, SearchParams, SearchResults } from './search';
+export type { LocalFileInfo, Stream, StreamCandidate } from './streaming';

packages/model/src/queue.ts

@@ -5,8 +5,6 @@ export type QueueItem = {
   track: Track;
   status: 'idle' | 'loading' | 'success' | 'error';
   error?: string;
-  activeStreamIndex: number;
-  failedStreamIndices: number[];
   addedAtIso: string;
 };
 

packages/model/src/streaming.ts

@@ -0,0 +1,36 @@
+import type { ProviderRef } from './index';
+
+export type Stream = {
+  url: string;
+  protocol: 'file' | 'http' | 'https' | 'hls';
+  mimeType?: string;
+  bitrateKbps?: number;
+  codec?: string;
+  container?: string;
+  qualityLabel?: string;
+  durationMs?: number;
+  contentLengthBytes?: number;
+  source: ProviderRef;
+};
+
+export type LocalFileInfo = {
+  fileUri: string;
+  fileSize?: number;
+  format?: string;
+  bitrateKbps?: number;
+  sampleRateHz?: number;
+  channels?: number;
+  fingerprint?: string;
+  scannedAtIso?: string;
+};
+
+export type StreamCandidate = {
+  id: string;
+  title: string;
+  durationMs?: number;
+  thumbnail?: string;
+  stream?: Stream;
+  lastResolvedAtIso?: string;
+  failed: boolean;
+  source: ProviderRef;
+};

packages/player/src/components/SoundProvider.tsx

@@ -3,15 +3,17 @@ import { useEffect } from 'react';
 
 import { Sound, Volume } from '@nuclearplayer/hifi';
 
+import { useStreamResolution } from '../hooks/useStreamResolution';
 import { useSettingsStore } from '../stores/settingsStore';
 import { useSoundStore } from '../stores/soundStore';
 
 export const SoundProvider: FC<PropsWithChildren> = ({ children }) => {
+  useStreamResolution();
   const { src, status, seek } = useSoundStore();
   const getValue = useSettingsStore((s) => s.getValue);
   const crossfadeMs = getValue('core.playback.crossfadeMs') as number;
-  const preload: 'none' | 'metadata' | 'auto' = 'auto';
-  const crossOrigin: '' | 'anonymous' | 'use-credentials' = '';
+  const preload: HTMLAudioElement['preload'] = 'auto';
+  const crossOrigin = '' as const;
   const volume01 = (getValue('core.playback.volume') as number) ?? 1;
   const muted = (getValue('core.playback.muted') as boolean) ?? false;
   const volumePercent = muted ? 0 : Math.round(volume01 * 100);