@rajeev02/media 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +178 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,178 @@
1
+ # @rajeev02/media
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@rajeev02/media.svg)](https://www.npmjs.com/package/@rajeev02/media)
4
+ [![license](https://img.shields.io/npm/l/@rajeev02/media.svg)](https://github.com/Rajeev02/rajeev-sdk/blob/main/LICENSE)
5
+
6
+ **Unified media player & download manager** with adaptive streaming (HLS/DASH), Picture-in-Picture, Chromecast/AirPlay, DRM (Widevine/FairPlay), quality selection, and offline downloads.
7
+
8
+ Part of [Rajeev SDK](https://github.com/Rajeev02/rajeev-sdk) — cross-platform infrastructure libraries for building apps that work everywhere.
9
+
10
+ ## Why use this?
11
+
12
+ - **Adaptive streaming** — HLS & DASH with automatic quality switching based on bandwidth
13
+ - **DRM support** — Widevine (Android/Web) and FairPlay (iOS) for premium content protection
14
+ - **Picture-in-Picture** — Floating video player while using other apps
15
+ - **Casting** — Chromecast and AirPlay integration with unified API
16
+ - **Offline downloads** — Background download with pause/resume, progress tracking, storage limits
17
+ - **Resume playback** — Automatic resume from last position across sessions
18
+ - **Playback speed** — 0.5x to 3x speed with pitch correction
19
+
20
+ ## ⚠️ Important: Native Media Player Required
21
+
22
+ This library provides the **playback state machine, download manager, and quality selection logic**. It does **NOT** render video/audio or decode media formats.
23
+
24
+ You need a native media player to pair with:
25
+
26
+ | Environment | Recommended library |
27
+ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
28
+ | Expo | [`expo-av`](https://docs.expo.dev/versions/latest/sdk/av/) |
29
+ | Bare React Native | [`react-native-video`](https://github.com/react-native-video/react-native-video) |
30
+ | Web | HTML5 `<video>` with [`hls.js`](https://github.com/video-dev/hls.js) / [`dash.js`](https://github.com/Dash-Industry-Forum/dash.js) |
31
+
32
+ **DRM:** If you use DRM-protected content, you must provide a license server URL:
33
+
34
+ - **Android/Web:** Widevine license server
35
+ - **iOS:** FairPlay license server
36
+ - **Providers:** [PallyCon](https://pallycon.com), [BuyDRM](https://www.buydrm.com), [Axinom](https://www.axinom.com)
37
+
38
+ **Casting:** Chromecast/AirPlay config types are provided, but actual casting requires native cast SDK setup in your app.
39
+
40
+ **Streaming:** Your HLS/DASH streams need a media server or CDN (AWS CloudFront, Mux, Cloudflare Stream, etc.).
41
+
42
+ **What this library provides:** Player state management (play/pause/seek/quality), download tracking with pause/resume, resume-from-last-position, and subtitle/audio track selection. Your native player handles the actual media rendering.
43
+
44
+ ## Platform Support
45
+
46
+ | Platform | Engine | Status |
47
+ | ---------- | ---------- | ------ |
48
+ | iOS 16+ | TypeScript | ✅ |
49
+ | Android 7+ | TypeScript | ✅ |
50
+ | Web | TypeScript | ✅ |
51
+
52
+ ## Installation
53
+
54
+ ```bash
55
+ npm install @rajeev02/media
56
+ ```
57
+
58
+ ### Peer Dependencies
59
+
60
+ - `react` >= 18.3.0
61
+ - `react-native` >= 0.84.0 _(optional)_
62
+
63
+ ## Quick Start
64
+
65
+ ### Media Player
66
+
67
+ ```typescript
68
+ import { MediaPlayerController } from "@rajeev02/media";
69
+
70
+ const player = new MediaPlayerController({
71
+ autoPlay: true,
72
+ enablePiP: true,
73
+ enableCast: true,
74
+ });
75
+
76
+ // Load a video with DRM
77
+ player.load({
78
+ uri: "https://stream.example.com/video.m3u8",
79
+ type: "video",
80
+ title: "My Movie",
81
+ drm: {
82
+ type: "widevine",
83
+ licenseServerUrl: "https://drm.example.com/license",
84
+ },
85
+ });
86
+
87
+ // Listen for events
88
+ player.on((event) => {
89
+ switch (event.type) {
90
+ case "progress":
91
+ updateSeekbar(event.currentTimeMs);
92
+ break;
93
+ case "quality_changed":
94
+ showBadge(event.quality);
95
+ break;
96
+ case "buffering":
97
+ showSpinner(event.isBuffering);
98
+ break;
99
+ }
100
+ });
101
+
102
+ // Playback controls
103
+ player.play();
104
+ player.pause();
105
+ player.seek(60_000); // Seek to 1 minute
106
+ player.setRate(1.5); // 1.5x speed
107
+ player.setQuality("720p"); // Manual quality selection
108
+ player.enterPiP(); // Picture-in-Picture
109
+ player.skipForward(10_000); // Skip 10 seconds
110
+ ```
111
+
112
+ ### Offline Downloads
113
+
114
+ ```typescript
115
+ import { DownloadManager } from "@rajeev02/media";
116
+
117
+ const dm = new DownloadManager(
118
+ 2, // Max concurrent downloads
119
+ 2 * 1024 ** 3, // 2 GB storage limit
120
+ );
121
+
122
+ // Enqueue download
123
+ dm.enqueue({
124
+ id: "movie-001",
125
+ uri: "https://cdn.example.com/movie.mp4",
126
+ title: "Offline Movie",
127
+ estimatedSizeBytes: 500_000_000, // 500 MB
128
+ });
129
+
130
+ // Track progress
131
+ dm.onProgress((progress) => {
132
+ console.log(`${progress.percentComplete}% at ${progress.speedBps} B/s`);
133
+ console.log(`ETA: ${progress.estimatedTimeRemainingMs}ms`);
134
+ });
135
+
136
+ // Manage downloads
137
+ dm.pause("movie-001");
138
+ dm.resume("movie-001");
139
+ dm.cancel("movie-001");
140
+ const all = dm.getAll(); // List all downloads with status
141
+ ```
142
+
143
+ ## API Reference
144
+
145
+ ### `MediaPlayerController`
146
+
147
+ | Method | Description |
148
+ | -------------------------------------- | ---------------------------- |
149
+ | `load(source)` | Load media source |
150
+ | `play()` / `pause()` | Play or pause |
151
+ | `seek(positionMs)` | Seek to position |
152
+ | `setRate(rate)` | Set playback speed (0.5–3.0) |
153
+ | `setQuality(quality)` | Set video quality |
154
+ | `setVolume(volume)` | Set volume (0–1) |
155
+ | `enterPiP()` / `exitPiP()` | Toggle Picture-in-Picture |
156
+ | `skipForward(ms)` / `skipBackward(ms)` | Skip forward/backward |
157
+ | `on(callback)` | Subscribe to player events |
158
+ | `destroy()` | Release player resources |
159
+
160
+ ### `DownloadManager`
161
+
162
+ | Method | Description |
163
+ | -------------------------- | ----------------------- |
164
+ | `enqueue(config)` | Start a download |
165
+ | `pause(id)` / `resume(id)` | Pause or resume |
166
+ | `cancel(id)` | Cancel and delete |
167
+ | `getAll()` | List all downloads |
168
+ | `getById(id)` | Get download status |
169
+ | `onProgress(callback)` | Track download progress |
170
+ | `getTotalStorageUsed()` | Get total bytes used |
171
+
172
+ ## Full Documentation
173
+
174
+ 📖 [Complete API docs with casting, DRM, and playlist support](https://github.com/Rajeev02/rajeev-sdk/blob/main/docs/usage/MEDIA.md)
175
+
176
+ ## License
177
+
178
+ MIT © 2026 [Rajeev Kumar Joshi](https://rajeev02.github.io)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rajeev02/media",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "Unified Media Player Engine — adaptive streaming, PiP, offline download, DRM, Hotstar/Netflix style",
5
5
  "main": "lib/index.js",
6
6
  "author": "Rajeev Kumar Joshi <rajeevjoshi91@gmail.com> (https://rajeev02.github.io)",