UNPKG

tiny-essentials

Version:

Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.

github.com/Tiny-Essentials/Tiny-Essentials

Tiny-Essentials/Tiny-Essentials

101 lines (74 loc) â€ĸ 4.97 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
# 🎧 TinyMediaPlayer Documentation `TinyMediaPlayer` is a robust, universal media player manager designed to orchestrate playback across multiple different media providers (such as YouTube, Spotify, etc.) using an **Adapter Pattern**. --- ## 🧩 Core Architecture: The Adapter Pattern To support different media platforms, `TinyMediaPlayer` relies on **Adapters**. You must create a class that extends `BaseMediaAdapter` for every new service you wish to support. ### 🛠ī¸ `BaseMediaAdapter` (Abstract Class) *This class cannot be instantiated directly. It serves as an interface.* | Method | Description | Parameters | Returns | | :--- | :--- | :--- | :--- | | `canHandle` | Checks if the adapter supports a specific content item. | `content: MediaContent` | `boolean` | | `play` | Starts or resumes playback. | `content: MediaContent` | `Promise<void>` | | `pause` | Pauses the current playback. | None | `Promise<void>` | | `stop` | Stops playback and resets the platform state. | None | `Promise<void>` | | `seek` | Jumps to a specific time. | `timeMs: number` | `Promise<void>` | | `getCurrentTime` | Gets the current playback position. | None | `number` (ms) | | `setVolume` | Sets the volume level. | `volume: number` (0.0 to 1.0) | `void` | --- ## 🚀 `TinyMediaPlayer` Class The main controller for managing playlists, playback state, and adapters. ### ⚙ī¸ Configuration (Constructor Options) When initializing `new TinyMediaPlayer(options)`, you can pass the following: * **`persistVolume`** (`boolean`): If `true`, the volume level is automatically saved to and loaded from `localStorage`. (Default: `false`). * **`volumeStorageKey`** (`string`): The key name used in `localStorage` to store the volume. (Default: `'tiny_media_player_volume'`). --- ### 🏗ī¸ Static Members #### Properties * **`unknownArtist`**: A global setting for when an artist's name is unavailable. * **Type**: `string` | `function` (returns a string). * **Getter/Setter**: Allows you to define a custom string or a logic-based function. #### Methods * **`parseContent(source, defaultMetadata, metadata, parseFile, callbacks)`**: * A static factory method to prepare a `MediaContent` object by extracting metadata from a URL or HTMLMediaElement. * **Returns**: `Promise<MediaContent>`. --- ### 📊 Instance Properties (Getters & Setters) | Property | Type | Description | | :--- | :--- | :--- | | `playlist` | `MediaContent[]` | Returns a shallow copy of the current playlist. | | `currentIndex` | `number` | The index of the currently playing track. | | `loopMode` | `'NONE' \| 'TRACK' \| 'PLAYLIST'` | Defines how the player behaves at the end of a track. | | `isRandom` | `boolean` | Enables or disables shuffle mode. | | `isPlaying` | `boolean` | Indicates if media is currently playing. | | `volume` | `number` | The current volume (constrained between `0.0` and `1.0`). | | `persistVolume` | `boolean` | Enables/disables volume saving to `localStorage`. | | `volumeStorageKey`| `string` | The key used for volume persistence. | --- ### 🕹ī¸ Methods #### 🔌 Adapter Management * **`registerAdapter(id, adapter)`**: Registers a new provider. * `id`: A unique string (e.g., `'youtube'`). * `adapter`: An instance of a class extending `BaseMediaAdapter`. #### 📋 Playlist Management * **`addTrack(content)`**: Adds a new `MediaContent` object to the end of the playlist. * **`existsTrack(index)`**: Returns `true` if a track exists at the given index. * **`getTrack(index)`**: Retrieves the track at the specified index. * **`removeTrack(index)`**: Removes a track. If the current track is removed, playback stops or adjusts. * **`searchTrack(query)`**: Searches the playlist. * `query`: A `string` (searches title, artist, or album) or a `function` (custom logic). * **Returns**: `SearchResult[]` (array of objects containing the track and its index). * **`clearPlaylist()`**: Stops playback and empties the playlist. #### ⏯ī¸ Playback Controls * **`play()`**: Starts playback of the current track. * **`pause()`**: Pauses the current track. * **`stop()`**: Stops the current track completely. * **`next()`**: Advances to the next track (respects `loopMode` and `isRandom`). * **`prev()`**: Returns to the previous track (respects `loopMode` and `isRandom`). * **`seek(timeMs)`**: Jumps to a specific millisecond in the current track. * **`step(stepMs)`**: Moves the timeline forward (positive) or backward (negative) by a specific amount. --- ## ⚠ī¸ Error Handling The class uses strict validation. The following errors may be thrown: * **`TypeError`**: Thrown when an argument is of the wrong type (e.g., passing a string to `volume`). * **`RangeError`**: Thrown when a number is out of allowed bounds (e.g., an index that doesn't exist or volume > 1.0). * **`Error`**: Thrown if no compatible adapter is found for the current content.