@francofantomius/jellyfin 0.1.0 → 0.4.0

package/README.md

@@ -3,8 +3,12 @@
 A modern, lightweight, modular, and type-safe Jellyfin SDK for Node.js and the Browser.
 
 [![npm version](https://img.shields.io/npm/v/@francofantomius/jellyfin.svg)](https://www.npmjs.com/package/@francofantomius/jellyfin)
+[![Documentation](https://img.shields.io/badge/docs-Material%20Design%203-6f42c1.svg)](https://francofantomius.github.io/jellyfin-sdk/)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+**Current Version: `v0.4.0`** (THE PROJECT IS BEING ACTIVELY DEVELOPED. WAIT FOR VERSION 0.5.0 TO USE IT)
+
+
 ---
 
 ## Features
@@ -15,12 +19,25 @@ A modern, lightweight, modular, and type-safe Jellyfin SDK for Node.js and the B
 - **Clean modular architecture**:
   - `client.auth` - Server authentication, user profiles, capabilities reporting.
   - `client.library` - Browse music and video libraries (movies, series, seasons, episodes, videos, search, playback info).
+  - `client.search` - Dedicated universal search with granular item type, genre, year, and library view scoping.
   - `client.media` - Universal audio and video stream URLs, HLS playlists, subtitles, direct downloads, and responsive artwork.
   - `client.playlists` - Create, edit, delete playlists, manage tracks, and upload cover images.
   - `client.playback` - Report playback start, progress, and stop to Jellyfin for scrobbling and playback sync.
   - `client.lyrics` - Fetch synced or unsynced song lyrics.
   - `client.favorites` - Toggle favorite items.
   - `client.offline` - Browser IndexedDB media download manager for offline audio and video playback.
+  - `client.resume` - Continue watching / resume items querying (`/UserItems/Resume`).
+  - `client.nextUp` - Next unplayed TV show episodes (`/Shows/NextUp`).
+  - `client.latest` - Recently added media (movies, episodes, albums) (`/Users/{userId}/Items/Latest`).
+  - `client.transcode` - Teardown active transcoding sessions (`/Videos/ActiveEncodings`).
+  - `client.websocket` - Real-time WebSocket event streaming, keep-alive heartbeat, and automated reconnection.
+  - `client.sessions` - Remote control active sessions, playback commands, volume adjustment, and message modals.
+  - `client.quickConnect` - Quick Connect pairing flow for TVs and secondary devices.
+  - `client.trickplay` - Jellyfin 10.9+ trickplay HLS tile manifests, image tiles, and scrubbing thumbnail coordinate calculations.
+  - `client.chapters` - Chapter navigation, preview thumbnails, typed MediaSegments, and intro/credits skipping.
+  - `client.genres` - Video genres, music genres, and production studios browsing.
+  - `client.collections` - BoxSet collection querying, creation, and item membership management.
+  - `client.displayPreferences` - Persist and retrieve view types, sorting configurations, and custom client UI preferences via `/DisplayPreferences/{id}`.
 - **Quality Settings & Presets**: Standard video (4K, 1080p, 720p, 480p, 360p, direct) and audio (320k, 256k, 192k, 128k, direct) presets and resolution utilities.
 - **Subtitles**: Direct VTT/SRT subtitle streaming URLs, raw text fetching, and automated track extraction from media metadata.
 - **Direct Downloads**: Server file download URLs, progress-tracked file downloads, and offline caching.
@@ -280,6 +297,238 @@ client.on('unauthorized', () => {
 
 ---
 
+### 11. Dashboard, Continue Watching & Next Up
+
+```typescript
+// Fetch in-progress items for Continue Watching carousels
+const resume = await client.resume.getResumeItems({
+  limit: 10,
+  mediaTypes: ['Video']
+});
+console.log('Continue watching:', resume.Items);
+
+// Fetch the next unplayed episodes for followed series
+const nextUp = await client.nextUp.getNextUp({
+  limit: 12,
+  enableTotalRecordCount: true
+});
+console.log('Next up episodes:', nextUp.Items);
+
+// Query recently added media across libraries or specific types
+const latestMovies = await client.latest.getLatestMovies({ limit: 10 });
+const latestEpisodes = await client.latest.getLatestEpisodes({ limit: 10 });
+const latestAlbums = await client.latest.getLatestAlbums({ limit: 10 });
+```
+
+---
+
+### 12. Active Transcode Session Teardown
+
+```typescript
+const playSessionId = 'playback-session-id';
+
+// Teardown active server transcoding to terminate lingering FFmpeg processes
+await client.transcode.stopActiveEncoding(playSessionId);
+
+// Or automatically teardown during playback stop reporting:
+await client.playback.reportStopped(movieId, currentTicks, { playSessionId });
+```
+
+---
+
+### 13. Universal & Scoped Search
+
+```typescript
+// Universal search across all items
+const results = await client.search.search('Inception', {
+  includeItemTypes: ['Movie', 'Series'],
+  genres: ['Sci-Fi'],
+  limit: 20
+});
+
+// Search within a specific library folder
+const musicResults = await client.search.searchInLibrary('music-library-id', 'Queen');
+
+// Media-specific search shortcuts
+const songs = await client.search.searchSongs('Yellow');
+const albums = await client.search.searchAlbums('Parachutes');
+const movies = await client.search.searchMovies('Interstellar');
+const series = await client.search.searchSeries('Breaking Bad');
+```
+
+---
+
+### 14. Real-time WebSocket Event Streaming
+
+```typescript
+// Connect to real-time WebSocket event feed
+client.websocket.connect({
+  autoReconnect: true,
+  keepAliveIntervalMs: 30000
+});
+
+// Listen to connection state
+client.websocket.on('open', () => console.log('WebSocket connected'));
+client.websocket.on('close', (code, reason) => console.log('WebSocket closed', code, reason));
+
+// Listen for library updates (scanned/added items)
+client.websocket.on('libraryChanged', (data) => {
+  console.log('Library changed. Items added:', data.ItemsAdded);
+});
+
+// Listen for user data updates (played state, favorites)
+client.websocket.on('userDataChanged', (data) => {
+  console.log('User data changed for user:', data.UserId);
+});
+
+// Subscribe to live session updates across the server
+client.websocket.startSessionsSubscription(2000);
+client.websocket.on('sessions', (sessions) => {
+  console.log('Active server sessions:', sessions);
+});
+```
+
+---
+
+### 15. Remote Control & Sessions Management
+
+```typescript
+// Query all active sessions
+const sessions = await client.sessions.getSessions();
+const targetSession = sessions.find((s) => s.DeviceName === 'Living Room TV');
+
+if (targetSession) {
+  // Remote playback control
+  await client.sessions.play(targetSession.Id, ['movie-id-1'], {
+    playCommand: 'PlayNow',
+    startPositionTicks: 0
+  });
+
+  // Playback commands
+  await client.sessions.pause(targetSession.Id);
+  await client.sessions.playPause(targetSession.Id);
+  await client.sessions.seek(targetSession.Id, 120_000_000); // 12 seconds in ticks
+
+  // Volume control
+  await client.sessions.setVolume(targetSession.Id, 75);
+  await client.sessions.toggleMute(targetSession.Id);
+
+  // Send an on-screen dialog message
+  await client.sessions.sendMessage(targetSession.Id, {
+    header: 'Notification',
+    text: 'Dinner is ready in 5 minutes!',
+    timeoutMs: 8000
+  });
+
+  // Instruct session to navigate to an item
+  await client.sessions.viewItem(targetSession.Id, 'Movie', 'movie-id-1', 'Inception');
+}
+```
+
+---
+
+### 16. Quick Connect Device Pairing Flow
+
+```typescript
+// On a secondary device (e.g. Smart TV or CLI app):
+if (await client.quickConnect.isEnabled()) {
+  const { Code, Secret } = await client.quickConnect.initiate();
+  console.log(`Enter this code on your phone/PC: ${Code}`);
+
+  // Automatically poll until authorized
+  const state = await client.quickConnect.poll(Secret, { intervalMs: 2000, timeoutMs: 120000 });
+  if (state.Authenticated && state.AuthenticationToken) {
+    client.accessToken = state.AuthenticationToken;
+    if (state.UserId) client.userId = state.UserId;
+    console.log('Successfully authenticated via Quick Connect!');
+  }
+}
+
+// On an already authenticated device (e.g. phone or PC):
+await client.quickConnect.authorize('123 456');
+console.log('Device authorized!');
+```
+
+---
+
+### 17. Trickplay & Scrubbing Thumbnails
+
+```typescript
+// Fetch manifest and available resolutions
+const item = await client.library.getItem('video-id');
+const resolutions = client.trickplay.getAvailableResolutions(item); // e.g. [320]
+
+// Calculate exact sprite coordinates for scrubbing seekbar
+const thumbnail = client.trickplay.getThumbnailForTimestamp({
+  item,
+  timestampMs: 45000, // 45 seconds into the video
+  width: 320
+});
+
+if (thumbnail) {
+  console.log(`Image: ${thumbnail.imageUrl}`);
+  console.log(`Offset: x=${thumbnail.x}px, y=${thumbnail.y}px, size=${thumbnail.width}x${thumbnail.height}px`);
+}
+```
+
+---
+
+### 18. Chapters & Intro / Credits Skipping
+
+```typescript
+// Fetch item chapters and images
+const chapters = await client.chapters.getChapters('episode-id');
+const chapterImage = client.chapters.getChapterImageUrl('episode-id', 1, { maxWidth: 400 });
+
+// Detect intro/credits from /MediaSegments or chapter heuristics
+const markers = await client.chapters.getIntroCredits('episode-id');
+
+// During playback, check if skip button should appear
+const currentTicks = 850_000_000; // 85s
+const activeSegment = client.chapters.findCurrentSegment(currentTicks, markers);
+if (activeSegment?.type === 'Intro') {
+  const skipToTicks = client.chapters.getSkipPosition(currentTicks, markers);
+  console.log(`Skip Intro available -> Jump to ${skipToTicks / 10_000_000}s`);
+}
+```
+
+---
+
+### 19. Genres, Studios & BoxSet Collections
+
+```typescript
+// Browse genres and studios
+const movieGenres = await client.genres.getGenres({ limit: 20 });
+const rockMusic = await client.genres.getMusicGenre('Rock');
+const studios = await client.genres.getStudios({ searchTerm: 'Universal' });
+
+// Browse and manage BoxSet Collections
+const collections = await client.collections.getCollections();
+const newBoxSet = await client.collections.createCollection({
+  name: 'Alien Anthology',
+  ids: ['alien-1', 'alien-2']
+});
+await client.collections.addToCollection(newBoxSet.Id, ['alien-3', 'alien-4']);
+await client.collections.removeFromCollection(newBoxSet.Id, 'alien-1');
+```
+
+---
+
+### 20. User Display Preferences
+
+```typescript
+// Get folder/view UI preferences
+const prefs = await client.displayPreferences.getDisplayPreferences('folder-id');
+
+// Update view layout and sorting
+await client.displayPreferences.setViewType('folder-id', 'Poster');
+await client.displayPreferences.setSortPreferences('folder-id', 'CommunityRating', 'Descending');
+await client.displayPreferences.setCustomPreference('folder-id', 'showBadges', 'true');
+```
+
+---
+
 ## License
 
 MIT © [Franco Fantomius](https://github.com/francofantomius)
+