From 967220af8c01c3c1b0eaba382e47271253973e14 Mon Sep 17 00:00:00 2001 From: dcvz Date: Tue, 19 Sep 2023 11:50:44 +0200 Subject: [PATCH] Add documentation --- docs/docs/api/events.md | 21 +++++++++++++++++++ docs/docs/api/objects/metadata.md | 34 +++++++++++++++++++++++++++++++ docs/docs/v4-migration.md | 12 +++++++++++ 3 files changed, 67 insertions(+) create mode 100644 docs/docs/api/objects/metadata.md diff --git a/docs/docs/api/events.md b/docs/docs/api/events.md index c398f18e1..36a82c1f3 100644 --- a/docs/docs/api/events.md +++ b/docs/docs/api/events.md @@ -40,6 +40,9 @@ Fired when the queue reaches the end. | position | `number` | The previous track position in seconds | ### `PlaybackMetadataReceived` + +**⚠️ Deprecated:** Please use `AudioChapterMetadataReceived`, `AudioTimedMetadataReceived`, `AudioCommonMetadataReceived`. + Fired when the current track receives metadata encoded in. (e.g. ID3 tags, Icy Metadata, Vorbis Comments or QuickTime metadata). | Param | Type | Description | @@ -199,3 +202,21 @@ event in the following situations: | --------- | --------- | -------------------------------------------- | | paused | `boolean` | On Android when `true` the player should pause playback, when `false` the player may resume playback. On iOS when `true` the playback was paused and when `false` the player may resume playback. | | permanent | `boolean` | Whether the interruption is permanent. On Android the player should stop playback. | + + +## Metadata + +### `AudioCommonMetadataReceived` +Fired when the current track receives metadata encoded in - static metadata not tied to a time. Usually received at start. + +Received data will be [`AudioCommonMetadataReceivedEvent`](./api/objects/metadata.md) - `raw` will always be `undefined`. + +### `AudioTimedMetadataReceived` +Fired when the current track receives metadata encoded in - dynamic metadata tied to a time. Events may be emitted over time. + +Received data will be [`AudioTimedMetadataReceivedEvent`](./api/objects/metadata.md). + +### `AudioChapterMetadataReceived` +Fired when the current track receives metadata encoded in - chapter overview data. Usually received at start. + +Received data will be [`AudioChapterMetadataReceivedEvent`](./api/objects/metadata.md). diff --git a/docs/docs/api/objects/metadata.md b/docs/docs/api/objects/metadata.md new file mode 100644 index 000000000..bb7ef23de --- /dev/null +++ b/docs/docs/api/objects/metadata.md @@ -0,0 +1,34 @@ +# AudioCommonMetadataReceivedEvent + +An object representing the metadata received for a track. + +| Param | Type | Description | +| -------- | -------- | --------------------------------------------------- | +| title | `string` | The track title. Might be undefined | +| artist | `string` | The track artist. Might be undefined | +| albumTitle | `string` | The track album. Might be undefined | +| subtitle | `string` | The track subtitle. Might be undefined | +| description | `string` | The track description. Might be undefined | +| artworkUri | `string` | The track artwork uri. Might be undefined | +| trackNumber | `string` | The track number. Might be undefined | +| composer | `string` | The track composer. Might be undefined | +| conductor | `string` | The track conductor. Might be undefined | +| genre | `string` | The track genre. Might be undefined | +| compilation | `string` | The track compilation. Might be undefined | +| station | `string` | The track station. Might be undefined | +| mediaType | `string` | The track media type. Might be undefined | +| creationDate | `string` | The track creation date. Might be undefined | +| creationYear | `string` | The track creation year. Might be undefined | +| raw | `RawEntry[]` | The raw metadata that was used to populate. May contain other non common keys. Might be undefined | + +# RawEntry + +An object representing a raw metadata entry. + +| Param | Type | Description | +| -------- | -------- | --------------------------------------------------- | +| commonKey | `string` | The common key. Might be undefined | +| keySpace | `string` | The key space. Might be undefined | +| time | `number` | The time. Might be undefined | +| value | `unknown` | The value. Might be undefined | +| key | `string` | The key. Might be undefined | diff --git a/docs/docs/v4-migration.md b/docs/docs/v4-migration.md index 1435b5263..399e74098 100644 --- a/docs/docs/v4-migration.md +++ b/docs/docs/v4-migration.md @@ -4,6 +4,13 @@ sidebar_position: 8 # Migrating from v3.2 to v4 +### General Additions + +1. [`getActiveTrackIndex()`](./api/functions/queue.md#getactivetrackindex) - Gets the index of the current track, or `undefined` if no track loaded. +1. [`getProgress()`](./api/functions/player.md#getprogress) - Returns progress, buffer and duration information. +1. [`getPlaybackState`](./api/functions/player.md#getplaybackstate) - Returns the current playback state. +1. [`Event.AudioChapterMetadataReceived`, `Event.AudioTimedMetadataReceived`, `Event.AudioCommonMetadataReceived`](./api/events.md#metadata): more detailed metadata events that are emitted when metadata is received from the native player. + ### `alwaysPauseOnInterruption` has been moved to [`AndroidOptions`](./api/objects/android-options.md) @@ -44,6 +51,11 @@ instead of `null` 1. `getBufferedPosition()` - Please use the `buffered` property returned by [`getProgress()`](./api/functions/player.md#getprogress). 1. `getCurrentTrack()` - Please use [`getActiveTrackIndex()`](./api/functions/queue.md#getactivetrackindex). 1. `Event.PlaybackTrackChanged` - Please use [`Event.PlaybackActiveTrackChanged`](./api/events.md#playbackactivetrackchanged). Also note that in 4.0 `Event.PlaybackTrackChanged` is no longer emitted when a track repeats. +1. `Event.PlaybackMetadataReceived` - Please use [`Event.AudioChapterMetadataReceived`, `Event.AudioTimedMetadataReceived`, `Event.AudioCommonMetadataReceived`](./api/events.md#metadata). + +### General Removals + +1. `clearMetadata()` - Instead use [`reset()`](./api/functions/player.md#reset) - which stops playback, clears the queue and clears the notification. ### Typescript Imports