icecast-metadata-player
Advanced tools
Simple to use Javascript class that plays an Icecast stream with real-time metadata updates
Icecast Metadata Player is a simple to use Javascript class that plays an Icecast stream with real-time metadata updates.
<script> tag.
audio/mpegaudio/aacapplication/oggaudio/mpeg, audio/aac, application/ogg (FLAC, Opus, Vorbis)audio/mpeg, audio/aac
application/ogg (FLAC, Opus, Vorbis)Media Source Extension support is expanded by wrapping the audio in the ISOBMFF (mp4) or WEBM containers using mse-audio-wrapper
Checkout this link to see which codecs your browser supports. https://cconcolato.github.io/media-mime-support/#audio_codecs
See the main page of this repo for other Icecast JS tools: https://github.com/eshaz/icecast-metadata-js
npm i icecast-metadata-playerDownload the latest build.
Include the file in a <script> tag in your html.
IcecastMetadataReader is made available as a global variable in your webpage to use wherever.
Example
<script src="icecast-metadata-player-1.0.0.min.js"></script>
<script>
const onMetadata = (metadata) => {
document.getElementById("metadata").innerHTML = metadata.StreamTitle;
};
const player =
new IcecastMetadataPlayer(
"https://dsmrad.io/stream/isics-all",
{ onMetadata }
);
</script>
<body>
<button onclick="player.play();"> Play </button>
<button onclick="player.stop();"> Stop </button>
<p> Now Playing: <span id="metadata"></span> </p>
</body>
To use IcecastMetadataPlayer, create a new instance by passing in the stream endpoint, and the options object (optional). See the Options and Callbacks sections for more information.
const player = new IcecastMetadataPlayer("https://stream.example.com", {
onMetadata: (metadata) => {console.log(metadata)},
...options
})
IcecastMetadataPlayer supports reading ICY metadata, Ogg (Vorbis Comment) metadata, or both. Each section below describes how to instantiate IcecastMetadataPlayer to use these different metadata types.
When reading ICY metadata, the client should be able to read the Icy-MetaInt header value on the response. If the CORS policy does not allow clients to read the Icy-MetaInt header, then IcecastMetadataPlayer will attempt to detect the metadata interval based on the incoming request data.
const player = new IcecastMetadataPlayer("https://stream.example.com/stream.mp3", {
onMetadata: (metadata) => {console.log(metadata)},
metadataTypes: ["icy"]
...options
})
OGG (Vorbis Comment) metadata, if available, usually offers more detail than ICY metadata.
const player = new IcecastMetadataPlayer("https://stream.example.com/stream.opus", {
onMetadata: (metadata) => {console.log(metadata)},
metadataTypes: ["ogg"]
...options
})
ICY and OGG metadata can both be read from the stream. Usually a stream will only have one or the other, but this option is possible if needed.
const player = new IcecastMetadataPlayer("https://stream.example.com/stream.flac", {
onMetadata: (metadata) => {console.log(metadata)},
metadataTypes: ["icy", "ogg"]
...options
})
To begin playing a stream, call the .play() method on the instance.
Note: IcecastMetadataPlayer will attempt to "fallback" to HTML5 with no metadata on any Media Source API issues. See the Troubleshooting section for more details.
const player = new IcecastMetadataPlayer("https://stream.example.com/stream.flac", {
onMetadata: (metadata) => {console.log(metadata)},
metadataTypes: ["icy"]
...options
})
player.play();
Metadata will be sent as soon as it is discovered via the onMetadataEnqueue callback and when the metadata is synchronized with the audio via the onMetadata callback. See the Methods section below for additional callbacks.
{
StreamTitle: "The stream's title", // ICY
StreamUrl: "The stream's url", // ICY
TITLE: "The stream's title", // OGG
ARTIST: "The stream's artist", // OGG
ALBUM: "The stream's album" // OGG
}
To stop playing the stream, call the stop() method on the instance.
player.stop();
See the HTML demos for examples.
IcecastMetadataPlayer enables retry / reconnect logic by default. When a fetch or network error occurs, IcecastMetadataPlayer will attempt to recover by retrying the fetch request.
This allows for seamless audio playback when switching networks, (i.e. from a cell network to a Wifi network).
See Retry Options to configure or disable reconnects.
error / onError event will be fired indicating the issue that caused the retry process to start.options object.
retry / onRetry event.stop() is called. orstreamstart / onStreamStart event will be fired and the audio will restart playing from the new request.retrytimeout / onRetryTimeout event will be fired and the stream will stop.The audio will continue to play until the buffer runs out while reconnecting. If the reconnect is successful before the buffer runs out, there will only be a minimal blip in playback after a network change.
To increase the amount of audio that is buffered by clients, increase the <burst-size> setting in your Icecast server.
player.play() async
player.stop() async
player.detachAudioElement()
player.audioElement
player.icyMetaInt
player.metadataQueue
metadata objects in FIFO order.
[
{
metadata: { StreamTitle: "Title 1" },
timestampOffset: 2.5,
timestamp: 1
},
{
metadata: { StreamTitle: "Title 2" },
timestampOffset: 5,
timestamp: 2
}
]
player.state
"loading", "playing", "stopping", "stopped", "retrying"You can create any number of instances of IcecastMetadataPlayer on your webpage.
Each instance must have it's own audio element.
const player_1 = new IcecastMetadataPlayer("https://example.com/stream_1", {
...options,
...callbacks
});
const player_2 = new IcecastMetadataPlayer("https://example.com/stream_2", {
...options,
...callbacks
})
endpoint (required)
audioElement (optional) - Default new Audio()
enableLogging (optional) Default false
true to enable warning and error logging to the consoleretryTimeout (optional) - Default 30 seconds
0 to disable retries(advanced retry logic)
retryDelayMin (optional) - Default 0.5 seconds
retryDelayMax (optional) - Default 2 seconds
retryDelayRate (optional) - Default 0.1 i.e. 10%
metadataTypes (optional) - Default ["icy"]
[] - Will not parse metadata["icy"] - Default Parse ICY metadata only["ogg"] - Parse OGG (vorbis comment) metadata only["icy", "ogg"] - Parse both ICY and OGG metadata["icy"] metadata type is enabledicyMetaInt (optional) Default reads from the response header
Icy-MetaInt header in the responseicyDetectionTimeout (optional) Default 2000
0 to disable metadata detectiononMetadata(metadata, timestampOffset, timestamp) Called when metadata is synchronized with the audio.
metadata ICY or Ogg metadata in an object of key value pairs
{ "StreamTitle: "The Stream Title" }{ "TITLE: "The Stream Title", "ARTIST": "Artist 1; Artist 2"... }timestampOffset time when is scheduled to be updated.timestamp time when metadata was discovered on the stream.onMetadataEnqueue(metadata, timestampOffset, timestamp) Called when metadata is discovered on the stream.
metadata ICY or Ogg metadata in an object of key value pairs
{ "StreamTitle: "The Stream Title" }{ "TITLE: "The Stream Title", "ARTIST": "Artist 1; Artist 2"... }timestampOffset time when is scheduled to be updated.timestamp time when metadata was discovered on the stream.onLoad() Called when the fetch request is started.onStreamStart() Called when fetch request begins to return data.onPlay() Called when the audio element begins playing.onStream(streamData) Called when stream data is sent to the audio element.onStreamEnd() Called when the fetch request completes.onStop() Called when the stream is completely stopped and all cleanup operations are complete.onRetry() Called when a retry / reconnect is attempted.onRetryTimeout() Called when the retry / reconnect attempts have stopped because they have timed-out.onWarn(message, ...messages) Called with message(s) when a warning condition is met.onError(message, ...messages) Called with message(s) when a fallback or error condition is met.onCodecUpdate({ ...codecInformation }) Called with audio codec information whenever there is a change
bitrate and samplingRate are passed in as an object to this callbackmse-audio-wrapper is being used to wrap the response in ISOBMFF or WEBMEach callback is made available as an event. The parameters for each callback are passed into event.details as an array.
player.addEventListener('metadata', (event) => {
const [metadata, timestampOffset, timestamp] = event.details;
})
IcecastMetadataPlayer builds are supplied with a source map, which allows the minified code to be viewed as fully formatted code in a browser debugger.
icecast-metadata-player-1.0.0.min.js.map located in the build folder of this project to the location along side icecast-metadata-player-1.0.0.min.js in your website.Passed in Icy-MetaInt is invalid. Attempting to detect ICY Metadata.
Icy-MetaInt header. IcecastMetadataPlayer will attempt to detect the ICY metadata interval, and will timeout after a default of 2 seconds, or the value in milliseconds passed into the icyDetectionTimeout option.This stream is not an OGG stream. No OGG metadata will be returned.
"ogg" passed into the metadataTypes options, but the stream response is not an ogg stream. ICY metadata and the stream will work without issues. Please remove the "ogg" option to remove this warning.Network request failed, possibly due to a CORS issue. Trying again without ICY Metadata.
Icy-MetaData: 1 header.
Media Source Extensions API in your browser does not support
codec,audio/mp4; codec="codec"
Falling back to HTML5 audio with no metadata updates. See the console for details on the error.
FAQs
Simple to use Javascript class that plays an Icecast stream with real-time metadata updates
The npm package icecast-metadata-player receives a total of 546 weekly downloads. As such, icecast-metadata-player popularity was classified as not popular.
We found that icecast-metadata-player demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.