Add documentation

doublesymmetry · Sep 19, 2023 · 967220a · 967220a
1 parent 5407ef2
commit 967220a
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 0 deletions.
diff --git 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
@@ -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
@@ -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