@cassette/core
@cassette/core
provides React Context-based components which expose an API for consuming and updating media player state. The API abstraction maps very closely to the set of actions that would be available to an end user of a conventional media player, while remaining flexible enough to accommodate varying media player design paradigms.
Installation
npm install @cassette/core
Components included:
FullscreenContextConsumer
- used to read and update the state of the surrounding fullscreenContext
FullscreenContextProvider
- wraps an area which should be fullscreen-ablePlayerContextConsumer
- used to read and update the state of the surrounding playerContext
PlayerContextGroup
- a wrapper which can be used to share configuration among multiple descendant PlayerContextProvider
instances as well as prevent multiple media elements from playing audio simultaneouslyPlayerContextProvider
- wraps an area which shares a common playerContext
Higher-order components included:
playerContextFilter
- consumes the surrounding fullscreenContext
and playerContext
and passes only a specified subset of the context, as well as any additional props, to the given child component
Find full documentation here!
[v2.0.0-beta.4] - 2019-09-26
v2 is a huge update! And yes, there are breaking changes. If you're just trying to upgrade from v1, you can check the Changed and Removed sections.
These notes are on changes since the previous stable release (v1.5.0). For changes that have occurred between alpha/beta releases, check the release notes.
All updates are mentioned on a broad level, but it wouldn't make sense to explain all new and changed APIs in minute detail here, so be sure to read the docs.
Changed
- The project has been renamed from react-responsive-audio-player to Cassette (#284, #291), and is now distributed in several packages (#292), so upgrading to version 2 will mean installing a new package or packages from npm. A simple upgrade will typically require only the
@cassette/player
package.
- Previously the package had a default export (
AudioPlayer
). AudioPlayer
has been renamed to MediaPlayer
and is a named export from @cassette/player
. So anything that previously looked like import AudioPlayer from 'react-responsive-audio-player'
will become import { MediaPlayer } from '@cassette/player'
. MediaPlayer
is the combination of two components: MediaPlayerControls
from the @cassette/player
package and PlayerContextProvider
(#214) from the @cassette/core
package. MediaPlayer
doesn't accept any unique props of its own, but rather all the props accepted by MediaPlayerControls
and PlayerContextProvider
. Discussion of prop changes or additions since v1 in this changelog section pertain to one of those two components.
- The
audioElementRef
prop to PlayerContextProvider
/MediaPlayer
has been renamed mediaElementRef
(#284) - A few minor style tweaks and improvements have been made for the player UI (#69, #94), but things look overall the same when you upgrade. However HTML and CSS have been totally refactored and classes renamed for v2 so any CSS extensions you wrote for v1 will need to be recreated using the new stylesheets for v2. (#42, #81)
- New/improved timestamp formatting in the default UI implementation from
@cassette/player
(#397) - Timestamp display always rounds down (#429).
- When an end user begins seeking with a progress bar or similar, the default behavior (which can be configured) is now to update the
currentTime
immediately instead of waiting until the user releases the mouse. (#204) - Initiating a forward skip during playback of the last track in a playlist, when the
cycle
prop is false
, no longer works - the action will be ignored and playback will continue. (#68) - Track duration is now reset to 0 when a new track is selected, then changes once metadata loads. To avoid this funny intermediate state, you should set the
duration
property on your tracks! (#372) - We no longer pause media when the
stalled
event fires (#166) - If a user tries to manually set the media
src
to something that isn't in the playlist, it will now be reset automatically to the previous state (#178) - Although things will still function without it, the
isUnboundedStream
property should be set on track objects that are indeed unbounded streams (e.g. radio) since one of our fixes means retrying media fetches that yield Infinity
duration. Setting isUnboundedStream
to true
skips the refetch. (#373) - Now requires a peer dependency of React v16.3 or higher (#138)
Removed
- The
onMediaEvent
prop is removed, since most of its use cases can be solved better now by using the PlayerContextProvider
(#226)
mediaElementRef
(previously called audioElementRef
(#284)) still exists as an escape hatch
- The
cycle
prop was removed. Use defaultRepeatStrategy
instead, and any subsequent updates should be set via playerContext
(since we would expect this setting to be changed as a result of an end user action) (#79) - Features deprecated in v1.x.x have now been totally removed:
- The
style
prop to AudioPlayer
(now MediaPlayer
) is no longer accepted. Use styles on a container element, or CSS, instead. - Mutating and re-using playlist arrays no longer works as expected. Playlists should be shallow copied if they need to be modified. See this docs entry for more information. (#268)
- The
displayText
property on a playlist track is removed in favor of the artist
and title
properties (also used by Media Session API) (#148).
- If this isn't enough, you can pass the
getDisplayText
prop to MediaPlayer
/MediaPlayerControls
.
- The
hideBackSkip
, hideForwardSkip
and disableSeek
props from AudioPlayer
in v1.x.x are not available on MediaPlayer
/MediaPlayerControls
. Use the controls
prop instead, which is more flexible.
Added
- Video (#206, #316) and fullscreen (#221) support!
- New
showVideo
prop for MediaPlayer
/MediaPlayerControls
can be set true to activate a video display (#221) - Can pass custom video display implementation to
MediaPlayer
/MediaPlayerControls
(#253) - Video display will show track album artwork for audio (#241)
- React Context-based API exposes media state and callbacks and allows totally custom player UI implementation (#138, #208)
- Besides what comes in the
@cassette/core
package, there is a @cassette/hooks
package for those who prefer to work with React hooks (#361)
PlayerContextGroup
can wrap multiple PlayerContextProvider
/MediaPlayer
instances to share configuration and prevent simultaneous audio playback (#219)- Several new control types for
@cassette/player
: volume (#72), mute (#257), repeat (#79), shuffle (#87), read-only progress (#60), fullscreen (#221) - Helper primitives for building custom UI (
ProgressBar
, ProgressBarDisplay
, MaybeMarquee
(#245), VideoDisplay
) available from @cassette/components
package (#292) - Keyboard navigation support for UI controls (#124, #396)
- New
controls
prop functionality for MediaPlayerControls
/MediaPlayer
- previously in v1 controls
supported a few control types as keywords, but in v2 several more built-in control keywords are supported, and custom controls can be implemented by passing in a function as a member of the controls
array (#42) - New props for
PlayerContextProvider
, which can also be passed to MediaPlayer
:
initialStateSnapshot
and onStateSnapshot
can be used to persist media player state and restore at load time later (#226)loadFirstTrackOnPlaylistComplete
can be set false
to prevent a playlist from resetting on the first track when the playlist finishes (#42)defaultVolume
, defaultMuted
, defaultPlaybackRate
, startingTrackIndex
(#61)defaultRepeatStrategy
(#79)maintainPlaybackRate
- can be set true
in order to override the default browser behavior which resets the playback rate on every new track (#129)seekMode
- for specifying whether to pause, seek immediately, or continue playback and seek after release, when seeking with a progress bar (#204)onActiveTrackUpdate
callback prop (#76, #406)onTrackPlaybackFailure
callback prop (#356)onTimeUpdate
callback prop (#369)
- Support for specifying multiple source audio files (e.g. ogg, mp3) for the same track (#178)
duration
property supported on playlist track objects so the player can display nicely before media has finished loading (#372)@cassette/player
exports components for individual player controls now (#42, #231, #341)- SCSS and CSS stylesheets for individual control components are now shipped for
@cassette/player
, in case you want to include only a subset of CSS you know you'll use. (#42) (#73, #231) - A
trackIndex
can now be passed to a play/pause button in order to tie that button to a particular track in the playlist (#338) - A
durationOverride
can be set on a media progress bar if you're running a live stream or similar and have stream duration info that isn't available to the media element (#379) - The media
title
attribute is now set, and configurable, for system notifcation support on iOS (#344) - You can set a
startingTime
property on a track object if you need to restore currentTime
from some previously recorded state (advanced use case) (#369) - You can now bring your own
HTMLMediaElement
implementation (#349) - You can now force the player to reload if something goes wrong with the network. (#426)
Fixed
- Prevent fullscreen player from opening automatically on iOS (#307)
- Fix issue with
undefined
crossOrigin
prop in Microsoft Edge (#368) - Proper time/progress display for unbounded streams e.g. radio (#377)
- Address weird infinity duration bug on iOS (#373)
- This fix means you should set the
isUnboundedStream
property on a playlist track if it is indeed an unbounded stream