Release v4.0.0 (#2177)

.github/workflows/nightly.yml

@@ -20,9 +20,9 @@ jobs:
       - name: Build Library
         run: yarn build
       - name: Extract Version
-        run: echo "LIB_VERSION=$(yarn info . version | head -2 | tail -1)" >> $GITHUB_ENV
+        run: echo "LIB_VERSION=$(cat package.json | jq -r .version)" >> $GITHUB_ENV
       - name: Set Nightly Version
-        run: yarn version --no-git-tag-version --no-commit-hooks --new-version ${{ env.LIB_VERSION }}-${{ github.sha }}
+        run: yarn version --no-git-tag-version --no-commit-hooks --new-version ${{ env.LIB_VERSION }}-nightly-${{ github.sha }}
       - uses: JS-DevTools/npm-publish@v1
         with:
           token: ${{ secrets.NPM_TOKEN }}

CHANGELOG.md

@@ -1,3 +1,15 @@
+# [4.0.0](https://github.com/doublesymmetry/react-native-track-player/compare/v4.0.0-rc09...v4.0.0) (2023-10-20)
+
+* **RN:** New metadata events have a new `metadata` property that contains the metadata that was received
+* **android:** Fix: allow updating duration in notification metadata
+* **ios:** Avoid prematurely activating audio session
+* **android:** Fix: don't emit both PlaybackTrackChanged when queue ends (parity with iOS)
+* **android:** Fix: allow progressUpdateEventInterval to be set to a decimal value (partial seconds)
+* **android:** Support for setting grace period before stopForeground (defaults to 5 seconds)
+* **ios:** Fix: updating rate will immediately reflect in control center
+* **android** Fix: issue where loading a new track after end required seek to start 
+* **ios:** Fix: crash adding output when load is called too fast
+
 # [4.0.0-rc09](https://github.com/doublesymmetry/react-native-track-player/compare/v4.0.0-rc08...v4.0.0-rc09) (2023-09-22)
 
 * **RN:** useIsPlaying hook now takes into account `none` state

android/build.gradle

@@ -49,9 +49,9 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.github.doublesymmetry:kotlinaudio:v2.0.0-rc17'
+    implementation 'com.github.doublesymmetry:kotlinaudio:v2.0.0'
     // used when building against local maven
-//    implementation "com.github.doublesymmetry:kotlin-audio:1.2.2"
+//    implementation "com.github.doublesymmetry:kotlin-audio:2.0.0"
 
     //noinspection GradleDynamicVersion
     implementation "com.facebook.react:react-native:+"

docs/docs/v4-migration.md

@@ -6,13 +6,18 @@ sidebar_position: 8
 
 ### 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.
+1. **New Function:** [`getActiveTrackIndex()`](./api/functions/queue.md#getactivetrackindex)
+  - Description: Gets the index of the current track, or `undefined` if no track loaded.
+2. **New Function:** [`getProgress()`](./api/functions/player.md#getprogress)
+  - Description: Returns progress, buffer and duration information.
+3. **New Function:**  [`getPlaybackState`](./api/functions/player.md#getplaybackstate)
+  - Description: Returns the current playback state.
+4. New Events: [`Event.AudioChapterMetadataReceived`, `Event.AudioTimedMetadataReceived`, `Event.AudioCommonMetadataReceived`](./api/events.md#metadata)
+  - Description: More detailed metadata events that are emitted when metadata is received from the native player.
 
+### General Changes
 
-### `alwaysPauseOnInterruption` has been moved to [`AndroidOptions`](./api/objects/android-options.md)
+- The configuration option `alwaysPauseOnInterruption` has been moved to the `android` section of options.
 
 ```diff
 await TrackPlayer.updateOptions({
@@ -23,47 +28,45 @@ await TrackPlayer.updateOptions({
 }
 ```
 
-### `usePlaybackState` initially returns `undefined`
+- On iOS, the pitch algorithm now defaults to `timeDomain` instead of `lowQualityZeroLatency`. The latter has been deprecated by Apple and has known issues on iOS 17.
 
-Have the [`usePlaybackState()`](./api/hooks.md##useplaybackstate) hook will
-return `{ state: undefined}` initially before it has finished retrieving the
-current state. Before it was incorrectly returning
-[`State.None`](./api/constants/state.md) which means no track is loaded.
+### Hook Behavior Updates
 
-### `remove()` supports removing current track
-You can now remove the current track with `remove()`. This was not allowed before.
-1. If the current track is removed, the next track will activated.
-2. If the current track was the last track in the queue, the first track will be activated.
+The [`usePlaybackState()`](./api/hooks.md##useplaybackstate) hook now initially returns `{ state: undefined }` before it has finished retrieving the current state. It previously returned [`State.None`](./api/constants/state.md), indicating no track loaded.
 
-### `getTrack` return type
+### Player Method Updates
 
-[`getTrack()`](./api/functions/queue.md#gettrack) now returns  `undefined`
-instead of `null`
+- The [`remove()`](./api/functions/queue.md#removeracks) function now supports removing the current track. If the current track is removed, the next track in the queue will be activated. If the current track was the last track in the queue, the first track will be activated.
 
-### Player `State` Updates
+The [`getTrack()`](./api/functions/queue.md#gettrack) function now returns `undefined` instead of `null`.
 
-1. [`State.Error`](./api/constants/state.md) - Emitted when an error state is encountered.
-1. [`State.Ended`](./api/constants/state.md) - State indicates playback stopped due to the end of the queue being reached.
-1. [`State.Loading`](./api/constants/state.md) - State indicating the initial loading phase of a track.
-1. [`State.Buffering`](./api/constants/state.md) - Now emitted no matter whether playback is paused or not.
-1. [`State.Connecting`](./api/constants/state.md) -  Deprecated. Please use `State.Loading` instead.
+### Player State Updates
+- New player states have been introduced and some updated
+1. [`State.Error`](./api/constants/state.md)
+  - **New.** Emitted when an error state is encountered.
+2. [`State.Ended`](./api/constants/state.md)
+  - **New.** State indicates playback stopped due to the end of the queue being reached.
+3. [`State.Loading`](./api/constants/state.md)
+  - **New.** State indicating the initial loading phase of a track.
+4. [`State.Buffering`](./api/constants/state.md)
+  - **Updated.** Now emitted no matter whether playback is paused or not.
+5. [`State.Connecting`](./api/constants/state.md)
+  - **Deprecated.** Please use `State.Loading` instead.
 
 ### General Deprecations
+- The following functions and events have been deprecated:
 
 1. `getState()` - Please use the `state` property returned by [`getPlaybackState()`](./api/functions/player.md#getplaybackstate).
-1. `getDuration()` -  Please use the `duration` property returned by [`getProgress()`](./api/functions/player.md#getprogress).
-1. `getPosition()` -  Please use the `position` property returned by [`getProgress()`](./api/functions/player.md#getprogress).
-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
+2. `getDuration()` -  Please use the `duration` property returned by [`getProgress()`](./api/functions/player.md#getprogress).
+3. `getPosition()` -  Please use the `position` property returned by [`getProgress()`](./api/functions/player.md#getprogress).
+4. `getBufferedPosition()` -  Please use the `buffered` property returned by [`getProgress()`](./api/functions/player.md#getprogress).
+5. `getCurrentTrack()` - Please use [`getActiveTrackIndex()`](./api/functions/queue.md#getactivetrackindex).
+6. `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.
+7. `Event.PlaybackMetadataReceived` - Please use [`Event.AudioChapterMetadataReceived`, `Event.AudioTimedMetadataReceived`, `Event.AudioCommonMetadataReceived`](./api/events.md#metadata).
 
-1. `clearMetadata()` - Instead use [`reset()`](./api/functions/player.md#reset) - which stops playback, clears the queue and clears the notification.
+### Removals
 
-### General Changes
-1. on iOS pitch algorithm defaults to `timeDomain` instead of `lowQualityZeroLatency`. It has been deprecated by Apple and has a few bugs on iOS 17.
+- The clearMetadata() function has been removed. Instead, use [`reset()`](./api/functions/player.md#reset), which stops playback, clears the queue, and clears the notification.
 
 ### Typescript Imports
 

docs/versioned_docs/version-4.0/api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "API Reference",
+  "position": 3
+}

docs/versioned_docs/version-4.0/api/constants/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Constants",
+  "position": 4
+}

docs/versioned_docs/version-4.0/api/constants/app-killed-playback-behavior.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 6
+---
+
+# App Killed Playback Behavior (android-only)
+
+```ts
+import { AppKilledPlaybackBehavior } from 'react-native-track-player';
+```
+
+## `ContinuePlayback` (default)
+
+This option will continue playing audio in the background when the app is
+removed from recents. The notification remains. This is the default.
+
+## `PausePlayback`
+
+This option will pause playing audio in the background when the app is removed
+from recents. The notification remains and can be used to resume playback.
+
+## `StopPlaybackAndRemoveNotification`
+
+This option will stop playing audio in the background when the app is removed
+from recents. The notification is removed and can't be used to resume playback.
+Users would need to open the app again to start playing audio.

docs/versioned_docs/version-4.0/api/constants/capability.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 2
+---
+
+# Capability
+
+All Capability types are made available through the named export `Capability`:
+
+```ts
+import { Capability } from 'react-native-track-player';
+```
+
+| Name | Description |
+|------|-------------|
+| `Play`           | Capability indicating the ability to play |
+| `PlayFromId`     | Capability indicating the ability to play from a track id (Required for Android Auto) |
+| `PlayFromSearch` | Capability indicating the ability to play from a text/voice search (Required for Android Auto) |
+| `Pause`          | Capability indicating the ability to pause |
+| `Stop`           | Capability indicating the ability to stop (on iOS available only for tracks where `.isLiveStream` is `true`) |
+| `SeekTo`         | Capability indicating the ability to seek to a position in the timeline |
+| `Skip`           | Capability indicating the ability to skip to any song in the queue |
+| `SkipToNext`     | Capability indicating the ability to skip to the next track |
+| `SkipToPrevious` | Capability indicating the ability to skip to the previous track |
+| `SetRating`      | Capability indicating the ability to set the rating value based on the rating type |
+| `JumpForward`    | Capability indicating the ability to jump forward by the amount of seconds specified in the options |
+| `JumpBackward`   | Capability indicating the ability to jump backward by the amount of seconds specified in the options |
+| `Like`           | (ios-only) Capability indicating the ability to like from control center |
+| `Dislike`        | (ios-only) Capability indicating the ability to dislike from control center |
+| `Bookmark`       | (ios-only) Capability indicating the ability to bookmark from control center |

docs/versioned_docs/version-4.0/api/constants/ios-category-mode.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 7
+---
+
+# iOS Category Mode (ios-only)
+
+All iOS Category Mode types are made available through the named export `IOSCategoryMode`:
+
+## `Default`
+
+The default audio session mode.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616579-default)
+
+## `GameChat`
+
+A mode that the GameKit framework sets on behalf of an application that
+uses GameKit’s voice chat service.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616511-gamechat)
+
+
+## `Measurement`
+
+A mode that indicates that your app is performing measurement of audio
+input or output.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616608-measurement)
+
+## `MoviePlayback`
+
+A mode that indicates that your app is playing back movie content.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616623-movieplayback)
+
+## `SpokenAudio`
+
+A mode used for continuous spoken audio to pause the audio when another
+app plays a short audio prompt.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616510-spokenaudio)
+
+## `VideoChat`
+
+A mode that indicates that your app is engaging in online video conferencing.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616590-videochat)
+
+## `VideoRecording`
+
+A mode that indicates that your app is recording a movie.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616535-videorecording)
+
+## `VoiceChat`
+
+A mode that indicates that your app is performing two-way voice communication,
+such as using Voice over Internet Protocol (VoIP).
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616455-voicechat)
+
+
+## `VoicePrompt`
+
+A mode that indicates that your app plays audio using text-to-speech.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/2962803-voiceprompt)

docs/versioned_docs/version-4.0/api/constants/ios-category-options.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 8
+---
+
+# iOS Category Options (ios-only)
+
+All iOS Category Options types are made available through the named export `IOSCategoryOptions`:
+
+```ts
+import { IOSCategoryOptions } from 'react-native-track-player';
+```
+
+## `MixWithOthers`
+
+An option that indicates whether audio from this session mixes with audio
+from active sessions in other audio apps.
+
+[See the Apple Docs ](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616611-mixwithothers)
+
+## `DuckOthers`
+
+An option that reduces the volume of other audio sessions while audio from
+this session plays.
+
+[See the Apple Docs ](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616618-duckothers)
+
+## `InterruptSpokenAudioAndMixWithOthers`
+
+An option that determines whether to pause spoken audio content from other
+sessions when your app plays its audio.
+
+[See the Apple Docs ](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616534-interruptspokenaudioandmixwithot)
+
+## `AllowBluetooth`
+
+An option that determines whether Bluetooth hands-free devices appear as
+available input routes.
+
+[See the Apple Docs ](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616518-allowbluetooth)
+
+## `AllowBluetoothA2DP`
+
+An option that determines whether you can stream audio from this session
+to Bluetooth devices that support the Advanced Audio Distribution Profile (A2DP).
+
+[See the Apple Docs ](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1771735-allowbluetootha2dp)
+
+## `AllowAirPlay`
+
+An option that determines whether you can stream audio from this session
+to AirPlay devices.
+
+[See the Apple Docs ](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1771736-allowairplay)
+
+## `DefaultToSpeaker`
+
+An option that determines whether audio from the session defaults to the
+built-in speaker instead of the receiver.
+
+[See the Apple Docs ](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616462-defaulttospeaker)

docs/versioned_docs/version-4.0/api/constants/ios-category.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 6
+---
+
+# iOS Category (ios-only)
+
+All iOS Category types are made available through the named export `IOSCategory`:
+
+```ts
+import { IOSCategory } from 'react-native-track-player';
+```
+
+## `Playback`
+
+The category for playing recorded music or other sounds that are central to the
+successful use of your app.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616509-playback)
+
+
+## `PlayAndRecord`
+
+The category for recording (input) and playback (output) of audio, such as for a
+Voice over Internet Protocol (VoIP) app.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616568-playandrecord)
+
+## `MultiRoute`
+
+The category for routing distinct streams of audio data to different output
+devices at the same time.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616484-multiroute) 
+
+## `Ambient`
+
+The category for an app in which sound playback is nonprimary — that is, your
+app also works with the sound turned off.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616560-ambient)
+
+## `SoloAmbient`
+
+The default audio session category.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616488-soloambient)
+
+## `Record`
+
+The category for recording audio while also silencing playback audio.
+
+[See the Apple Docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616451-record)