tiny-essentials 1.28.7 → 1.28.9

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 (55) hide show
  1. package/changelog/1/28/9.md +17 -0
  2. package/dist/v1/TinyBasicsEs.min.js +1 -1
  3. package/dist/v1/TinyDebugger.min.js +1 -0
  4. package/dist/v1/TinyEssentials.min.js +1 -1
  5. package/dist/v1/TinyMediaPlayer.min.js +1 -1
  6. package/dist/v1/TinyRadioFm.min.js +1 -1
  7. package/dist/v1/TinyUploadClicker.min.js +1 -1
  8. package/dist/v1/basics/browserDetector.cjs +228 -0
  9. package/dist/v1/basics/browserDetector.d.mts +66 -0
  10. package/dist/v1/basics/browserDetector.mjs +207 -0
  11. package/dist/v1/basics/index.cjs +6 -0
  12. package/dist/v1/basics/index.d.mts +2 -1
  13. package/dist/v1/basics/index.mjs +2 -1
  14. package/dist/v1/build/TinyDebugger.cjs +7 -0
  15. package/dist/v1/build/TinyDebugger.d.mts +3 -0
  16. package/dist/v1/build/TinyDebugger.mjs +2 -0
  17. package/dist/v1/index.cjs +8 -0
  18. package/dist/v1/index.d.mts +3 -1
  19. package/dist/v1/index.mjs +4 -2
  20. package/dist/v1/libs/TinyDebugger.cjs +380 -0
  21. package/dist/v1/libs/TinyDebugger.d.mts +132 -0
  22. package/dist/v1/libs/TinyDebugger.mjs +351 -0
  23. package/dist/v1/libs/TinyMediaPlayer/HtmlAudio.cjs +39 -3
  24. package/dist/v1/libs/TinyMediaPlayer/HtmlAudio.d.mts +10 -0
  25. package/dist/v1/libs/TinyMediaPlayer/HtmlAudio.mjs +35 -3
  26. package/dist/v1/libs/TinyMediaPlayer/HtmlVideo.cjs +39 -3
  27. package/dist/v1/libs/TinyMediaPlayer/HtmlVideo.d.mts +10 -0
  28. package/dist/v1/libs/TinyMediaPlayer/HtmlVideo.mjs +35 -3
  29. package/dist/v1/libs/TinyMediaPlayer/Mock.cjs +333 -0
  30. package/dist/v1/libs/TinyMediaPlayer/Mock.d.mts +154 -0
  31. package/dist/v1/libs/TinyMediaPlayer/Mock.mjs +296 -0
  32. package/dist/v1/libs/TinyMediaPlayer/SoundCloud.cjs +30 -0
  33. package/dist/v1/libs/TinyMediaPlayer/SoundCloud.d.mts +10 -0
  34. package/dist/v1/libs/TinyMediaPlayer/SoundCloud.mjs +26 -0
  35. package/dist/v1/libs/TinyMediaPlayer/Youtube.cjs +39 -3
  36. package/dist/v1/libs/TinyMediaPlayer/Youtube.d.mts +10 -0
  37. package/dist/v1/libs/TinyMediaPlayer/Youtube.mjs +32 -3
  38. package/dist/v1/libs/TinyMediaPlayer/index.cjs +18 -0
  39. package/dist/v1/libs/TinyMediaPlayer/index.d.mts +10 -0
  40. package/dist/v1/libs/TinyMediaPlayer/index.mjs +16 -0
  41. package/dist/v1/libs/TinyMediaPlayer.cjs +156 -31
  42. package/dist/v1/libs/TinyMediaPlayer.d.mts +43 -7
  43. package/dist/v1/libs/TinyMediaPlayer.mjs +148 -31
  44. package/dist/v1/libs/TinyPromiseQueue.cjs +6 -4
  45. package/dist/v1/libs/TinyPromiseQueue.d.mts +8 -6
  46. package/dist/v1/libs/TinyPromiseQueue.mjs +6 -4
  47. package/dist/v1/libs/TinyRadioFm.cjs +271 -138
  48. package/dist/v1/libs/TinyRadioFm.d.mts +67 -3
  49. package/dist/v1/libs/TinyRadioFm.mjs +239 -123
  50. package/docs/v1/README.md +2 -0
  51. package/docs/v1/basics/browserDetector.md +135 -0
  52. package/docs/v1/libs/TinyDebugger.md +119 -0
  53. package/docs/v1/libs/TinyMediaPlayer.md +26 -22
  54. package/docs/v1/libs/TinyRadioFm.md +25 -3
  55. package/package.json +13 -1
package/docs/v1/README.md CHANGED
@@ -21,6 +21,7 @@ Here, you can navigate through different sections of the project. Below are the
21
21
  - 📺 **[FullScreen](./basics/fullScreen.md)** — A complete fullscreen API manager with detection, event handling, and cross-browser compatibility.
22
22
  - 🧱 **[Collision](./basics/collision.md)** — Full-featured rectangle collision detection system with directional analysis, depth calculation, and center offset metrics.
23
23
  - 🎵 **[MediaContent](./basics/mediaContent.md)** — A comprehensive media processing module for downloading audio, extracting rich ID3 metadata, and managing image blobs for album art.
24
+ - 📦 **[BrowserDetector](./basics/browserDetector.md)** — A multi-layered JavaScript utility for identifying the user's web browser and rendering engine.
24
25
 
25
26
  ### 2. **`libs/`**
26
27
  - 🗂️ **[TinyPromiseQueue](./libs/TinyPromiseQueue.md)** — A class that allows sequential execution of asynchronous tasks, supporting task delays, cancellation, and queue management.
@@ -64,6 +65,7 @@ Here, you can navigate through different sections of the project. Below are the
64
65
  * 🧠 **[TinyMamdaniInferenceSystem](./libs/TinyMamdaniInferenceSystem.md)** — A implementation of a Mamdani Inference System, allowing you to model logic using trapezoidal membership functions.
65
66
  * 📻 **[TinyRadioFm](./libs/TinyRadioFm.md)** — It is designed to handle complex playback sequences, including music and voice playlists, scheduled timeline mutations, and custom content injections, all while maintaining absolute reproducibility through a mathematical seed.
66
67
  * ⏯️ **[TinyMediaPlayer](./libs/TinyMediaPlayer.md)** — A universal media player architecture utilizing an adapter pattern to orchestrate multiple platform APIs, featuring robust playlist management, playback controls, and weighted random selection.
68
+ * 🛠️ **[TinyDebugger](./libs/TinyDebugger.md)** — A lightweight, event-driven debugging utility designed to wrap standard `console` methods. It provides enhanced features such as custom prefixes, color support, and the ability to emit events whenever a log occurs, making it perfect for complex applications where you might want to redirect logs to an external service or a UI component.
67
69
 
68
70
  ### 2.1. **`libs/TinyClassManager`**
69
71
 
@@ -0,0 +1,135 @@
1
+ # 🌐 Browser Detection Toolkit
2
+
3
+ A multi-layered JavaScript utility for identifying the user's web browser and rendering engine.
4
+
5
+ ## 📋 Table of Contents
6
+ 1. [Data Types](#📋-data-types)
7
+ 2. [Core Functions](#🛠️-core-functions)
8
+ - [isBrowserAgent](#1-isbrowseragent)
9
+ - [getBrowserCssPrefix](#2-getbrowsercssprefix)
10
+ - [getDuckTyping](#3-getducktyping)
11
+ 3. [Advanced Detection](#🎯-advanced-detection)
12
+ - [getBrowserPings](#4-getbrowserpings)
13
+ - [browserIs](#5-browseris)
14
+
15
+ ---
16
+
17
+ ## 📋 Data Types
18
+
19
+ To ensure type safety and clarity, the toolkit utilizes the following definitions:
20
+
21
+ ### `BrowserDetected`
22
+ A union type representing the supported browser names:
23
+ `'chrome' | 'firefox' | 'ie' | 'edge' | 'safari' | 'opera' | 'yandex' | 'other'`
24
+
25
+ ### `DuckTypingResult`
26
+ An object returned by feature detection, containing boolean flags:
27
+ | Property | Description |
28
+ | :--- | :--- |
29
+ | `isOpera` | `true` if Opera is detected |
30
+ | `isFirefox` | `true` if Firefox is detected |
31
+ | `isSafari` | `true` if Safari is detected |
32
+ | `isIE` | `true` if Internet Explorer is detected |
33
+ | `isEdge` | `true` if Microsoft Edge is detected |
34
+ | `isChrome` | `true` if Google Chrome is detected |
35
+ | `isBlink` | `true` if the Blink rendering engine is detected |
36
+
37
+ ---
38
+
39
+ ## 🛠️ Core Functions
40
+
41
+ ### 1. `isBrowserAgent()`
42
+ Parses the `navigator.userAgent` string to provide a quick identification of the browser.
43
+
44
+ * **Returns:** `BrowserDetected`
45
+ * **Best use case:** Quick, lightweight checks where absolute precision is not critical.
46
+
47
+ ```javascript
48
+ import { isBrowserAgent } from 'tiny-essentials/basics/browserDetector';
49
+
50
+ const browser = isBrowserAgent();
51
+ console.log(`You are using: ${browser}`);
52
+ // Output example: "chrome"
53
+ ```
54
+
55
+ ### 2. `getBrowserCssPrefix()`
56
+ Inspects the computed styles of the document to determine the CSS rendering engine.
57
+
58
+ * **Returns:** `'gecko' | 'webkit' | 'trident' | 'other'`
59
+ * **Best use case:** When you need to apply CSS vendor prefixes or handle engine-specific rendering quirks.
60
+
61
+ ```javascript
62
+ import { getBrowserCssPrefix } from 'tiny-essentials/basics/browserDetector';
63
+
64
+ const engine = getBrowserCssPrefix();
65
+ if (engine === 'webkit') {
66
+ console.log("Applying WebKit specific styles... 🎨");
67
+ }
68
+ ```
69
+
70
+ ### 3. `getDuckTyping()`
71
+ Performs deep feature detection by checking for the existence of specific global objects and APIs.
72
+
73
+ * **Returns:** `DuckTypingResult`
74
+ * **Best use case:** When you need to know exactly which features are available in the current environment.
75
+
76
+ ```javascript
77
+ import { getDuckTyping } from './browserDetector.js';
78
+
79
+ const features = getDuckTyping();
80
+
81
+ if (features.isChrome) {
82
+ console.log("Chrome-specific API available! ✅");
83
+ }
84
+
85
+ if (features.isBlink) {
86
+ console.log("Blink engine detected. ⚡");
87
+ }
88
+ ```
89
+
90
+ ---
91
+
92
+ ## 🎯 Advanced Detection
93
+
94
+ These functions aggregate the results from the core functions to provide the highest possible accuracy.
95
+
96
+ ### 4. `getBrowserPings(disable = [])`
97
+ Aggregates detection results from all three methods (User Agent, CSS Prefix, and Duck Typing) to provide a "ping count" for each browser.
98
+
99
+ * **Parameters:**
100
+ * `disable` (Array): An optional array of `BrowserDetected` names to exclude from the results.
101
+ * **Returns:** `Object<BrowserDetected, number>` (An object where keys are browsers and values are the number of times they were detected).
102
+ * **Throws:** `TypeError` if `disable` is not an array or contains invalid browser names.
103
+
104
+ ```javascript
105
+ import { getBrowserPings } from 'tiny-essentials/basics/browserDetector';
106
+
107
+ // Get detection counts for all browsers
108
+ const counts = getBrowserPings();
109
+ console.log(counts);
110
+
111
+ // Get counts while ignoring Internet Explorer
112
+ const filteredCounts = getBrowserPings(['ie']);
113
+ console.log(filteredCounts);
114
+ ```
115
+
116
+ ### 5. `browserIs(disable = [])`
117
+ The most reliable method. It runs all detection strategies and returns the browser that received the highest number of "pings."
118
+
119
+ * **Parameters:**
120
+ * `disable` (Array): An optional array of `BrowserDetected` names to exclude.
121
+ * **Returns:** `BrowserDetected` (The most likely browser name).
122
+ * **Throws:** `TypeError` if `disable` is not an array or contains invalid browser names.
123
+
124
+ ```javascript
125
+ import { browserIs } from 'tiny-essentials/basics/browserDetector';
126
+
127
+ // Get the most accurate browser identification
128
+ const currentBrowser = browserIs();
129
+
130
+ if (currentBrowser === 'firefox') {
131
+ console.log("Welcome, Firefox user! 🦊");
132
+ } else {
133
+ console.log(`Detected: ${currentBrowser}`);
134
+ }
135
+ ```
@@ -0,0 +1,119 @@
1
+ # 🛠️ TinyDebugger Documentation
2
+
3
+ `TinyDebugger` is a lightweight, event-driven debugging utility designed to wrap standard `console` methods. It provides enhanced features such as custom prefixes, color support, and the ability to emit events whenever a log occurs, making it perfect for complex applications where you might want to redirect logs to an external service or a UI component.
4
+
5
+ ## 🚀 Quick Start
6
+
7
+ To use `TinyDebugger`, import it into your project and initialize it with a configuration object.
8
+
9
+ ```javascript
10
+ import TinyDebugger from 'tiny-essentials/libs/TinyDebugger';
11
+
12
+ const debuggerInstance = new TinyDebugger({
13
+ logger: console, // You can use standard console or a custom object
14
+ id: 'APP_CORE',
15
+ debugMode: true,
16
+ canEmitLogs: true,
17
+ useLogColors: true
18
+ });
19
+
20
+ debuggerInstance.log('info', 'Hello, Yasmin! The debugger is ready. 🌟');
21
+ ```
22
+
23
+ ---
24
+
25
+ ## ⚙️ Configuration
26
+
27
+ When creating a new instance via the `constructor`, you can pass a configuration object with the following properties:
28
+
29
+ | Property | Type | Required | Default | Description |
30
+ | :--- | :--- | :--- | :--- | :--- |
31
+ | `logger` | `Object` | **Yes** | N/A | An object implementing the `Console` interface. |
32
+ | `id` | `string` | **Yes** | N/A | A unique identifier for this debugger instance. |
33
+ | `debugMode` | `boolean` | **Yes** | N/A | If `false`, all logging methods will return immediately. |
34
+ | `canEmitLogs` | `boolean` | No | `false` | If `true`, the instance will emit events for every log action. |
35
+ | `useLogColors` | `boolean` | No | `false` | Enables ANSI color codes. *Note: Automatically disabled in Firefox.* |
36
+
37
+ ---
38
+
39
+ ## ✨ Key Features
40
+
41
+ ### 🎨 Custom Colors
42
+ You can inject colors into your log messages using the `_colorName_` syntax.
43
+ * **Syntax:** `_color_`
44
+ * **Example:** `debugger.log('info', 'This is _red_ critical error!');`
45
+
46
+ ### 🏷️ Custom Prefixes
47
+ You can use placeholders to insert specific prefix text into your logs.
48
+ * **Syntax:** `:id:`
49
+ * **Example:** `debugger.log('info', ':info: System initialized.');`
50
+
51
+ ### 📡 Event Emission
52
+ If `canEmitLogs` is set to `true`, `TinyDebugger` acts as an `EventEmitter`, allowing you to listen to specific debugging events. This is incredibly useful for building custom developer consoles in web applications.
53
+
54
+ ---
55
+
56
+ ## 📖 API Reference
57
+
58
+ ### `log(logType, message, ...args)`
59
+ The primary method for logging.
60
+ * **logType:** `'log' | 'info' | 'warn' | 'error' | 'debug' | 'dirxml' | 'group' | 'groupCollapsed' | 'trace'`
61
+ * **message:** `string` (The text to display)
62
+ * **args:** `...any` (Additional data to inspect)
63
+
64
+ ### `logLabel(logType, label)`
65
+ Logs a specific console type associated with a label.
66
+ * **logType:** `'count' | 'countReset' | 'time' | 'timeEnd' | 'profile' | 'profileEnd' | 'timeStamp'`
67
+ * **label:** `string`
68
+
69
+ ### `logTimeLabel(label, ...args)`
70
+ Starts a timer with a specific label.
71
+ * **label:** `string`
72
+
73
+ ### `logAssert(condition, ...args)`
74
+ Logs a message only if the provided condition evaluates to `false`.
75
+ * **condition:** `boolean`
76
+
77
+ ### `logDir(item, options)`
78
+ Displays an element as a JavaScript object (similar to `console.dir`).
79
+ * **item:** `any`
80
+ * **options:** `InspectOptions`
81
+
82
+ ### `logTable(tabularData, properties)`
83
+ Displays data in a clean, readable table.
84
+ * **tabularData:** `any`
85
+ * **properties:** `string[]` (Optional array of column properties)
86
+
87
+ ### `logClear()`
88
+ Clears the console.
89
+ ### `logGroupEnd()`
90
+ Ends the current console group.
91
+
92
+ ---
93
+
94
+ ## 🛠️ Advanced Customization
95
+
96
+ You can dynamically modify the behavior of your debugger instance using these internal methods:
97
+
98
+ | Method | Description |
99
+ | :--- | :--- |
100
+ | `_addLogColor(id, code)` | Adds a new color shortcut (e.g., `_mycolor_`). |
101
+ | `_removeLogColor(id)` | Removes a color shortcut. |
102
+ | `_addLogPrefix(id, text)` | Adds a new prefix shortcut (e.g., `:status:`). |
103
+ | `_removeLogPrefix(id)` | Removes a prefix shortcut. |
104
+
105
+ ### Example: Adding a Custom Color
106
+ ```javascript
107
+ debuggerInstance._addLogColor('gold', '\x1b[33m');
108
+ debuggerInstance.log('info', 'This message is _gold_!');
109
+ ```
110
+
111
+ ---
112
+
113
+ ## ⚠️ Error Handling
114
+
115
+ It will throw `TypeError` if:
116
+ 1. The `logger` provided is not a valid object.
117
+ 2. The `id` is not a string.
118
+ 3. Configuration booleans are provided as other types.
119
+ 4. An invalid `logType` is passed to the logging methods.
@@ -1,6 +1,6 @@
1
1
  # 🎧 TinyMediaPlayer Documentation
2
2
 
3
- `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**.
3
+ `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**. It inherits debugging capabilities from `TinyDebugger`.
4
4
 
5
5
  ---
6
6
 
@@ -11,33 +11,31 @@ To support different media platforms, `TinyMediaPlayer` relies on **Adapters**.
11
11
  ### 🛠️ `BaseMediaAdapter` (Abstract Class)
12
12
  *This class cannot be instantiated directly. It serves as an interface that all specific API wrappers must extend and implement.*
13
13
 
14
- #### Properties
15
- | Property | Type | Description |
16
- | :--- | :--- | :--- |
17
- | `destroyed` | `boolean` | Indicates if the adapter instance has been destroyed. |
18
-
19
14
  #### Methods
20
15
  | Method | Description | Parameters | Returns |
21
16
  | :--- | :--- | :--- | :--- |
17
+ | `static canHandle` | Determines if the adapter can play the provided content. | `content: MediaContent` | `boolean` |
22
18
  | `canHandle` | Determines if the adapter can play the provided content. | `content: MediaContent` | `boolean` |
23
19
  | `isReady` | Synchronously checks if the adapter is ready. | None | `boolean` |
20
+ | `isPaused` | Checks whether the media adapter is paused. | None | `boolean` |
21
+ | `isEnded` | Checks whether the media adapter is ended. | None | `boolean` |
24
22
  | `waitIsReady` | Asynchronously waits until the adapter is ready. | None | `Promise<void>` |
25
23
  | `play` | Starts or resumes playback of the provided content. | `content: MediaContent` | `Promise<void>` |
26
24
  | `pause` | Pauses the current playback. | None | `Promise<void>` |
27
- | `stop` | Stops the playback completely and resets the platform state. | None | `Promise<void>` |
25
+ | `stop` | Stops the playback completely and resets the internal platform state. | None | `Promise<void>` |
28
26
  | `seek` | Seeks to a specific time in the media timeline. | `timeMs: number` | `Promise<void>` |
29
27
  | `isMuted` | Checks whether the player is currently muted. | None | `boolean \| null` |
30
28
  | `mute` | Mutes the current playback. | None | `Promise<void>` |
31
29
  | `unMute` | Unmutes the current playback. | None | `Promise<void>` |
32
- | `getCurrentTime` | Retrieves the current playback position. | None | `number` (ms) |
30
+ | `getCurrentTime` | Retrieves the current playback time from the underlying API. | None | `number` (ms) |
33
31
  | `getTotalDuration` | Gets the total duration of the content. | None | `number` (ms) |
34
32
  | `getRemainingTime` | Gets the remaining time until the content ends. | None | `number` (ms) |
35
33
  | `getPlaybackPercentage` | Gets the percentage of the content that has been played. | None | `number` (0 to 100) |
36
34
  | `getTimeData` | Retrieves a consolidated object containing all time-related metrics. | None | `ContentTimeData` |
37
35
  | `setVolume` | Sets the playback volume for the underlying API. | `volume: number` (0.0 to 1.0) | `void` |
38
- | `getVolume` | Gets the current playback volume. | None | `number` (0.0 to 1.0) |
39
- | `getContentData` | Retrieves the metadata of the loaded content. | None | `Promise<ContentData>` |
40
- | `destroy` | Cleans up the instance and marks it as destroyed. | None | `void` |
36
+ | `getVolume` | Gets the playback volume from the underlying API. | None | `number` (0.0 to 1.0) |
37
+ | `getContentData` | Retrieves the metadata of the currently loaded content. | None | `Promise<ContentData>` |
38
+ | `destroy` | Cleans up the instance. | None | `void` |
41
39
 
42
40
  ---
43
41
 
@@ -90,11 +88,6 @@ import { BaseMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Base';
90
88
  * @extends BaseMediaAdapter
91
89
  */
92
90
  class MyCustomServiceAdapter extends BaseMediaAdapter {
93
- /**
94
- * Determines if this adapter can play the given content.
95
- * @param {MediaContent} content - The media content to check.
96
- * @returns {boolean} - True if the URL matches the service.
97
- */
98
91
  static canHandle(content) {
99
92
  return content.url.startsWith('https://example.com/');
100
93
  }
@@ -116,6 +109,8 @@ class MyCustomServiceAdapter extends BaseMediaAdapter {
116
109
  async getContentData() { return {}; }
117
110
  async waitIsReady() {}
118
111
  isReady() { return true; }
112
+ isPaused() { return false; }
113
+ isEnded() { return false; }
119
114
  isMuted() { return false; }
120
115
  async mute() {}
121
116
  async unMute() {}
@@ -123,6 +118,7 @@ class MyCustomServiceAdapter extends BaseMediaAdapter {
123
118
  getRemainingTime() { return 0; }
124
119
  getPlaybackPercentage() { return 0; }
125
120
  getTimeData() { return {}; }
121
+ destroy() {}
126
122
  }
127
123
 
128
124
  // Registering the custom adapter
@@ -166,6 +162,9 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
166
162
  * **`repeatCurrentOnPrev`** (`boolean`): If `true`, clicking 'previous' repeats the current track on the first click. (Default: `false`).
167
163
  * **`smoothPlayPauseVolume`** (`boolean`): If `true`, volume fades smoothly during play/pause transitions. (Default: `false`).
168
164
  * **`smoothStopVolume`** (`boolean`): If `true`, volume fades smoothly to zero when stopping. (Default: `false`).
165
+ * **`debugMode`** (`boolean`): Whether to enable internal debug logging.
166
+ * **`useLogColors`** (`boolean`): Whether to enable log color support.
167
+ * **`logger`** (`Console`): A custom logger object.
169
168
 
170
169
  ---
171
170
 
@@ -204,7 +203,7 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
204
203
  | `isRandom` | `boolean` | Enables or disables shuffle mode. |
205
204
  | `isPlaying` | `boolean` | Indicates if media is currently playing. |
206
205
  | `volume` | `number` | The current volume level (strictly between `0.0` and `1.0`). |
207
- | `isMuted` | `boolean` | Sets the mute state of the player. |
206
+ | `isMuted` | `boolean` | Indicates if the player is currently muted. |
208
207
 
209
208
  #### 🎨 UX & Customization
210
209
  | Property | Type | Description |
@@ -253,7 +252,7 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
253
252
  * **`existsTrack(index)`**: Returns `true` if the track exists at the given index.
254
253
  * **`getTrack(index)`**: Retrieves the track at the specified index.
255
254
  * **`removeTrack(index)`**: **(Async)** Removes a track and adjusts the current index/playback accordingly.
256
- * **`searchTrack(query)`**: Searches the playlist.
255
+ * **`searchTrack(query)`**: Searches the playlist (string or function).
257
256
  * `query`: A `string` (searches title, artist, or album) or a `function` (custom logic).
258
257
  * **Returns**: `SearchResult[]` (array of objects containing the track and their corresponding indices).
259
258
  * **`clearPlaylist()`**: **(Async)** Stops playback and empties the entire playlist.
@@ -264,19 +263,24 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
264
263
  * **`stop()`**: **(Async)** Stops the current track completely.
265
264
  * **`next()`**: **(Async)** Advances to the next track (respects `loopMode` and `isRandom`).
266
265
  * **`prev()`**: **(Async)** Returns to the previous track (respects `loopMode` and `isRandom`).
266
+ * **`skipTo(index)`**: **(Async)** Jumps to a specific index in the playlist.
267
267
  * **`seek(timeMs)`**: **(Async)** Jumps to a specific millisecond in the current track.
268
268
  * **`step(stepMs)`**: **(Async)** Moves the timeline forward (+) or backward (-) by `stepMs`.
269
+ * **`mute()`**: **(Async)** Mutes the current playback.
270
+ * **`unMute()`**: **(Async)** Unmutes the current playback.
269
271
 
270
272
  #### ⏳ Time Utilities
271
273
  * **`getCurrentTime()`**: Gets the current playback time in milliseconds.
272
274
  * **`getTotalDuration()`**: Gets the total duration of the current track in milliseconds.
273
275
  * **`getRemainingTime()`**: Gets the remaining time until the current track ends in milliseconds.
274
276
  * **`getPlaybackPercentage()`**: Gets the percentage of the current track that has been played (0-100).
275
- * **`getContentData()`**: Retrieves structured metadata for the current content.
277
+ * **`isPaused`**: **(Getter)** Checks if the adapter is paused.
278
+ * **`isEnded`**: **(Getter)** Checks if the adapter has ended.
279
+ * **`getContentData()`**: **(Async)** Retrieves structured metadata for the current content.
276
280
  * **`waitIsReady()`**: **(Async)** Waits until the active adapter is fully initialized.
277
281
 
278
282
  #### ♻️ Lifecycle
279
- * **`destroy()`**: **(Async)** Safely stops playback, clears state, removes adapters, and detaches all listeners to prevent memory leaks.
283
+ * **`destroy()`**: **(Async)** Safely stops playback, clears state, removes adapters, and detaches all listeners.
280
284
 
281
285
  ---
282
286
 
@@ -318,6 +322,6 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
318
322
  ## ⚠️ Error Handling
319
323
 
320
324
  The class uses strict validation. The following errors may be thrown:
321
- * **`TypeError`**: Thrown when an argument is of the wrong type (e.g., invalid index type, non-boolean options, invalid adapter instance, or empty storage key).
322
- * **`RangeError`**: Thrown when a number is out of allowed bounds (e.g., negative time, volume outside `0.0`-`1.0`, negative durations, or index out of playlist bounds).
325
+ * **`TypeError`**: Thrown when an argument is of the wrong type.
326
+ * **`RangeError`**: Thrown when a number is out of allowed bounds.
323
327
  * **`Error`**: Thrown if no compatible adapter is found for the current content.
@@ -31,7 +31,9 @@ The behavior of the engine is controlled via the `RadioConfig` object.
31
31
  | `voiceAfterMusic` | `boolean` | `true` | If `true`, voice messages play after music tracks. |
32
32
  | `voiceMin` | `number` | `0` | Minimum number of voice messages to play in a cycle. |
33
33
  | `voiceMax` | `number` | `1` | Maximum number of voice messages to play in a cycle. |
34
+ | `musicMinConsecutive`| `number` | `0` | Min times a music track must repeat consecutively. |
34
35
  | `musicMaxConsecutive`| `number` | `0` | Max consecutive music repeats (`-1` = unlimited, `0` = no repeats). |
36
+ | `voiceMinConsecutive`| `number` | `0` | Min times a voice track must repeat consecutively. |
35
37
  | `voiceMaxConsecutive`| `number` | `0` | Max consecutive voice repeats (`-1` = unlimited, `0` = no repeats). |
36
38
 
37
39
  ---
@@ -60,7 +62,7 @@ Adds new content to the engine immediately.
60
62
  * **Parameters:**
61
63
  * `type`: `'music' | 'voice' | 'custom'`.
62
64
  * `data`: The `MediaContent` object (must include `id` and `duration`).
63
- * `smartQueue`: If `true`, delays insertion until the current content ends (primarily for `custom`).
65
+ * `smartQueue`: If `true`, delays insertion until the end of the content playing at that timestamp (primarily for `custom`).
64
66
  * **Emits:** `contentAdded`
65
67
 
66
68
  #### `remove(id)`
@@ -108,7 +110,7 @@ Predicts upcoming events from a specific date forward using a virtual sandbox to
108
110
  ### 💾 Persistence & Lifecycle
109
111
 
110
112
  #### `async exportState()`
111
- Exports the entire radio state (playlists, tasks, seed, config) as a JSON string. Automatically converts all image Blob URLs to **Base64** for portability.
113
+ Exports the entire radio state (playlists, tasks, seed, config) as a JSON string. Automatically converts all image Blob URLs to **Base64** for easy storage.
112
114
  * **Returns:** `Promise<string>`
113
115
 
114
116
  #### `importState(json)`
@@ -138,4 +140,24 @@ An instruction to change the radio state.
138
140
  * `timestamp`: Execution time.
139
141
  * `action`: `'add' | 'remove' | 'move'`.
140
142
  * `type`: `'music' | 'voice'`.
141
- * `payload`: Action-specific data.
143
+ * `payload`: Action-specific data (`MediaContent`, `string`, or `ScheduledMovePayload`).
144
+
145
+ ### `CustomPosition` 📍
146
+ Represents content injected at a specific absolute timestamp.
147
+ * `content`: The `MediaContent` object.
148
+ * `intendedTimestamp`: The target absolute timestamp.
149
+ * `originalTimestamp`: The timestamp preserved for intelligent repositioning.
150
+
151
+ ### `ScheduledMovePayload` 🚚
152
+ Data required to relocate an existing item within a playlist.
153
+ * `id`: Content ID to move.
154
+ * `newIndex`: The target index in the playlist.
155
+
156
+ ### `CycleBlock` 🔄
157
+ A structural block representing a single full iteration of the radio sequence.
158
+ * `items`: Items belonging to this cycle.
159
+ * `duration`: Total duration of the cycle block in ms.
160
+ * `lastMusicId`: ID of the last music played in this block.
161
+ * `musicConsecutiveCount`: Current consecutive count for music.
162
+ * `lastVoiceId`: ID of the last voice played in this block.
163
+ * `voiceConsecutiveCount`: Current consecutive count for voice.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tiny-essentials",
3
- "version": "1.28.7",
3
+ "version": "1.28.9",
4
4
  "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
5
5
  "bin": {
6
6
  "tiny-essentials-fork": "./TinyFork.mjs"
@@ -112,6 +112,10 @@
112
112
  "require": "./dist/v1/basics/promiseUtils.cjs",
113
113
  "import": "./dist/v1/basics/promiseUtils.mjs"
114
114
  },
115
+ "./basics/browserDetector": {
116
+ "require": "./dist/v1/basics/browserDetector.cjs",
117
+ "import": "./dist/v1/basics/browserDetector.mjs"
118
+ },
115
119
  "./fileManager": {
116
120
  "require": "./dist/v1/fileManager/index.cjs",
117
121
  "import": "./dist/v1/fileManager/index.mjs"
@@ -156,6 +160,10 @@
156
160
  "require": "./dist/v1/libs/TinyMediaPlayer/HtmlVideo.cjs",
157
161
  "import": "./dist/v1/libs/TinyMediaPlayer/HtmlVideo.mjs"
158
162
  },
163
+ "./libs/TinyMediaPlayer/Mock": {
164
+ "require": "./dist/v1/libs/TinyMediaPlayer/Mock.cjs",
165
+ "import": "./dist/v1/libs/TinyMediaPlayer/Mock.mjs"
166
+ },
159
167
  "./libs/TinyMediaPlayer/docs/YouTubePlayer": {
160
168
  "require": "./dist/v1/libs/TinyMediaPlayer/docs/YouTubePlayer.cjs",
161
169
  "import": "./dist/v1/libs/TinyMediaPlayer/docs/YouTubePlayer.mjs"
@@ -168,6 +176,10 @@
168
176
  "require": "./dist/v1/libs/TinyRadioFm.cjs",
169
177
  "import": "./dist/v1/libs/TinyRadioFm.mjs"
170
178
  },
179
+ "./libs/TinyDebugger": {
180
+ "require": "./dist/v1/libs/TinyDebugger.cjs",
181
+ "import": "./dist/v1/libs/TinyDebugger.mjs"
182
+ },
171
183
  "./libs/UltraRandomMsgGen": {
172
184
  "require": "./dist/v1/libs/UltraRandomMsgGen.cjs",
173
185
  "import": "./dist/v1/libs/UltraRandomMsgGen.mjs"