@francofantomius/jellyfin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franco Fantomius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# @francofantomius/jellyfin
+
+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)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## Features
+
+- **TypeScript-first**: Full type definitions for Jellyfin items, audio and video metadata, subtitles, search parameters, and responses.
+- **Universal / Isomorphic**: Runs seamlessly in Node.js (scripts, server-side apps, SSR) and the Browser (vanilla, React, Vue, Svelte, Electron).
+- **Dual module exports**: Native ESM (`import`) and CommonJS (`require`).
+- **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.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.
+- **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.
+- **Flexible storage & caching**: Built-in memory and local storage adapters with Stale-While-Revalidate caching support.
+- **Event-driven**: Listen to events like `unauthorized`, `authenticated`, and `logout`.
+
+---
+
+## Installation
+
+```bash
+npm install @francofantomius/jellyfin
+```
+
+Or with yarn / pnpm:
+
+```bash
+pnpm add @francofantomius/jellyfin
+yarn add @francofantomius/jellyfin
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize Client & Authenticate
+
+```typescript
+import { JellyfinClient } from '@francofantomius/jellyfin';
+
+const client = new JellyfinClient({
+  serverUrl: 'https://jellyfin.example.com',
+  clientInfo: {
+    name: 'My Media App',
+    version: '1.0.0',
+    device: 'Web Browser'
+  }
+});
+
+// Authenticate using username and password
+const authResult = await client.authenticate('username', 'password');
+console.log('Logged in as:', authResult.User.Name);
+console.log('Access token:', client.accessToken);
+```
+
+If you already have a stored token and user ID:
+
+```typescript
+const client = new JellyfinClient({
+  serverUrl: 'https://jellyfin.example.com',
+  accessToken: 'your-saved-access-token',
+  userId: 'your-user-id'
+});
+```
+
+---
+
+### 2. Browse Music, Movies & Series
+
+```typescript
+// Browse music
+const albums = await client.library.getAlbums({ limit: 20 });
+const songs = await client.library.getSongs({ limit: 50, albumId: albums.Items[0]?.Id });
+
+// Browse video libraries
+const videoViews = await client.library.getVideoLibraries();
+
+// Browse movies (with genres and year filtering)
+const movies = await client.library.getMovies({
+  limit: 25,
+  genres: ['Action', 'Sci-Fi'],
+  sortBy: 'CommunityRating',
+  sortOrder: 'Descending'
+});
+
+// Browse TV series, seasons, and episodes
+const series = await client.library.getSeries({ limit: 20 });
+const seasons = await client.library.getSeasons(series.Items[0].Id);
+const episodes = await client.library.getEpisodes(series.Items[0].Id, seasons.Items[0]?.Id);
+
+// Request playback negotiation info (sources, audio/subtitle streams)
+const playbackInfo = await client.library.getPlaybackInfo(movies.Items[0].Id);
+```
+
+---
+
+### 3. Video Streaming & Quality Presets
+
+```typescript
+import { VIDEO_QUALITY_PRESETS, resolveVideoQuality, formatBitrate } from '@francofantomius/jellyfin';
+
+const movieId = 'some-movie-id';
+
+// Direct play video stream URL
+const directVideoUrl = client.media.getVideoStreamUrl(movieId, {
+  static: true,
+  container: 'mp4'
+});
+
+// Transcoded video stream URL with a quality preset
+const transcodeVideoUrl = client.media.getVideoStreamUrl(movieId, {
+  quality: '1080p', // Automatically sets 10 Mbps bitrate, 1920x1080
+  audioStreamIndex: 1,
+  subtitleStreamIndex: 2,
+  subtitleMethod: 'Encode'
+});
+
+// Adaptive HLS video playlist URL
+const videoHlsUrl = client.media.getVideoHlsStreamUrl(movieId, {
+  quality: '720p',
+  segmentLength: 4
+});
+
+// Inspect quality presets
+console.log(VIDEO_QUALITY_PRESETS['1080p'].label); // "1080p (10 Mbps)"
+console.log(formatBitrate(10_000_000)); // "10 Mbps"
+```
+
+---
+
+### 4. Subtitles
+
+```typescript
+const movie = movies.Items[0];
+
+// Extract subtitle tracks from item metadata
+const subtitleTracks = client.media.getSubtitleTracks(movie);
+subtitleTracks.forEach((track) => {
+  console.log(`${track.displayTitle} (${track.codec}) -> ${track.url}`);
+});
+
+// Generate subtitle stream URL
+const vttUrl = client.media.getSubtitleUrl(movie.Id, movie.MediaSources[0].Id, 2, {
+  format: 'vtt'
+});
+
+// Fetch raw subtitle text (e.g. WebVTT or SRT content)
+const subtitleText = await client.media.getSubtitles(movie.Id, movie.MediaSources[0].Id, 2, {
+  format: 'vtt'
+});
+```
+
+---
+
+### 5. Downloads & Offline Storage
+
+```typescript
+const itemId = 'some-item-id';
+
+// Get server direct download URL (unmodified original file)
+const downloadUrl = client.media.getDownloadUrl(itemId, { filename: 'movie.mp4' });
+
+// Download file as a Blob with progress
+const blob = await client.media.downloadFile(itemId, {
+  onProgress: (fraction) => console.log(`Download: ${(fraction * 100).toFixed(0)}%`)
+});
+
+// Offline Storage Manager (IndexedDB caching in browser)
+if (client.offline.isSupported()) {
+  // Download audio or video item
+  await client.offline.downloadItem(movie, (progress) => {
+    console.log(`Offline download: ${(progress * 100).toFixed(0)}%`);
+  });
+
+  // Check if downloaded
+  const isDownloaded = await client.offline.isItemDownloaded(movie.Id);
+
+  // Get local object URL for offline playback
+  const localBlobUrl = await client.offline.getDownloadedBlobUrl(movie.Id);
+}
+```
+
+---
+
+### 6. Audio Streaming & Artwork URLs
+
+```typescript
+const trackId = 'some-track-id';
+
+// Universal audio streaming URL
+const streamUrl = client.media.getAudioStreamUrl(trackId, {
+  quality: '320k', // or maxStreamingBitrate: '320000'
+  startTimeTicks: 0
+});
+
+// Artwork URL (with custom dimensions and quality)
+const album = albums.Items[0];
+const artworkUrl = client.media.getArtworkUrl(album, {
+  maxWidth: 500,
+  quality: 90,
+  fallbackUrl: '/assets/placeholder-cover.png'
+});
+```
+
+---
+
+### 7. Playback Reporting (Scrobbling & Sync)
+
+```typescript
+// When track starts playing
+await client.playback.reportStart(trackId, 0);
+
+// Periodic progress update (e.g. every 10 seconds)
+await client.playback.reportProgress(trackId, positionTicks, false);
+
+// When playback stops or completes
+await client.playback.reportStopped(trackId, positionTicks);
+```
+
+---
+
+### 8. Playlists
+
+```typescript
+// Create a playlist
+const playlistId = await client.playlists.createPlaylist({
+  name: 'Favorites 2026',
+  trackIds: ['track-id-1', 'track-id-2']
+});
+
+// Add more tracks
+await client.playlists.addTracks(playlistId, ['track-id-3']);
+
+// Upload a custom cover image (base64)
+await client.playlists.uploadPlaylistImage(playlistId, base64JpgData, 'image/jpeg');
+
+// Fetch playlist items
+const playlistItems = await client.playlists.getPlaylistItems(playlistId);
+
+// Delete playlist
+await client.playlists.deletePlaylist(playlistId);
+```
+
+---
+
+### 9. Synced Lyrics & Favorites
+
+```typescript
+// Fetch song lyrics
+const lyrics = await client.lyrics.getLyrics(trackId);
+console.log(lyrics?.Lyrics); // [{ Start: 10000000, Text: 'Hello world' }, ...]
+
+// Toggle favorites
+await client.favorites.markFavorite(trackId);
+await client.favorites.unmarkFavorite(trackId);
+```
+
+---
+
+### 10. Handling Unauthorized Sessions
+
+```typescript
+client.on('unauthorized', () => {
+  console.warn('Jellyfin session has expired. Redirecting to login...');
+});
+```
+
+---
+
+## License
+
+MIT © [Franco Fantomius](https://github.com/francofantomius)