Gathering detailed insights and metrics for icecast-metadata-player
Gathering detailed insights and metrics for icecast-metadata-player
Browser and NodeJS packages for playing and reading Icecast compatible streaming audio with realtime metadata updates.
Installations
npm install icecast-metadata-playerDeveloper Guide
BETA
Typescript
Yes
Module System
ESM
Node Version
22.15.0
NPM Version
11.3.0
Releases
128
icecast-metadata-player/1.17.12
icecast-metadata-player/1.17.12
Updated on May 04, 2025
icecast-metadata-player/1.17.10
icecast-metadata-player/1.17.10
Updated on Apr 26, 2025
icecast-matadata-player/1.17.9
icecast-matadata-player/1.17.9
Updated on Dec 15, 2024
icecast-metadata-player/1.17.8
icecast-metadata-player/1.17.8
Updated on Dec 15, 2024
icecast-metadata-player/1.17.7
icecast-metadata-player/1.17.7
Updated on Dec 10, 2024
icecast-metadata-player/1.17.6
icecast-metadata-player/1.17.6
Updated on Nov 15, 2024
Languages
4
JavaScript
HTML
CSS
XSLT
JavaScript (69%)
HTML (29.37%)
CSS (1.21%)
XSLT (0.42%)
Developer
eshaz
Download Statistics
Total Downloads
65,974
Last Day
1
Last Week
377
Last Month
2,334
Last Year
27,997
GitHub Statistics
188 Stars
484 Commits
25 Forks
8 Watchers
5 Branches
2 Contributors
Updated on Jun 21, 2025
Bundle Size
71.72 kB
Minified
21.78 kB
Minified + Gzipped
Sponsor this package
Maintainers
1
Package Meta Information
Latest Version
1.17.12
Package Id
icecast-metadata-player@1.17.12
Unpacked Size
1.40 MB
Size
644.71 kB
File Count
32
NPM Version
11.3.0
Node Version
22.15.0
Published on
May 04, 2025
Total Downloads
Cumulative downloads
Total Downloads
65,974
Last Day
-85.7%
1
Compared to previous day
Last Week
-39.5%
377
Compared to previous week
Last Month
-29.8%
2,334
Compared to previous month
Last Year
28.7%
27,997
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Icecast Metadata Player
Icecast Metadata Player is browser library that plays streaming audio with full cross-platform codec support and real-time metadata updates.
- Plays streaming audio using Media Source Extensions API, Web Assembly audio decoders, and HTML5 audio.
- Provides synchronized ICY metadata and Ogg metadata updates.
- Seamless playback during network changes (i.e. Wifi to Cell network).
- Seamlessly switch between endpoints during playback (i.e. moving between load balanced streams, or streams with different codecs).
- Lazy loading of dependencies for faster and more efficient load times.
- Available as an NPM Package and as a file to include in a
<script>tag.- See Installing
Checkout the demos here!
See the main page of this repo for other Icecast JS tools: https://github.com/eshaz/icecast-metadata-js
Supported codecs:
- MP3
audio/mpeg,audio/mp4 - AAC
audio/aac,audio/mp4 - FLAC
audio/flac, application/ogg,audio/mp4 - Opus
application/ogg,audio/mp4,audio/webm - Vorbis
application/ogg,audio/webm
Supported Browsers:
- All major browsers (Chrome, Firefox, Opera, Android, iOS 12.4 and higher, Safari Desktop)
- Check your Browser Here
Contents
Installing
Install via NPM
-
npm i icecast-metadata-playerExample
1import IcecastMetadataPlayer from "icecast-metadata-player"; 2 3const player = new IcecastMetadataPlayer( 4 "https://dsmrad.io/stream/isics-all", 5 { onMetadata: (metadata) => {console.log(metadata)} } 6);
Install as a standalone script
-
Download all of the files here for the latest build and save these to a path on your server.
- Each module is automatically downloaded to the browser as needed.
- All
*.jsfiles must be saved into the same path on your server. - The
*.js.mapfiles are optional source maps for debugging.Filename Functionality icecast-metadata-player-1.17.12.main.min.jsCore functionality (playback, metadata)
Use this file in your<script>tagicecast-metadata-player-1.17.12.synaudio.min.jsGapless playback support icecast-metadata-player-1.17.12.mediasource.min.jsMediasource playback support icecast-metadata-player-1.17.12.mpeg.min.jsMPEG playback support (webaudio) icecast-metadata-player-1.17.12.flac.min.jsFLAC playback support (webaudio) icecast-metadata-player-1.17.12.opus.min.jsOpus playback support (webaudio) icecast-metadata-player-1.17.12.vorbis.min.jsVorbis playback support (webaudio) icecast-metadata-player-1.17.12.common.min.jsCommon functions (webaudio)
-
Add a
<script>tag referencingicecast-metadata-player-1.17.12.main.min.jsin your html. -
IcecastMetadataPlayeris made available as a global variable in your webpage to use wherever.Example
1<script src="icecast-metadata-player-1.17.12.main.min.js"></script> 2<script> 3 const onMetadata = (metadata) => { 4 document.getElementById("metadata").innerHTML = metadata.StreamTitle; 5 }; 6 const player = 7 new IcecastMetadataPlayer( 8 "https://dsmrad.io/stream/isics-all", 9 { onMetadata } 10 ); 11</script> 12<body> 13 <button onclick="player.play();"> Play </button> 14 <button onclick="player.stop();"> Stop </button> 15 <p> Now Playing: <span id="metadata"></span> </p> 16</body>
Usage
-
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.1const player = new IcecastMetadataPlayer("https://stream.example.com", { 2 onMetadata: (metadata) => {console.log(metadata)}, 3 ...options 4})IcecastMetadataPlayer supports reading ICY metadata, Ogg (Vorbis Comment) metadata, or both. Each section below describes how to instantiate
IcecastMetadataPlayerto use these different metadata types.ICY Metadata
-
When reading ICY metadata, the client should be able to read the
Icy-MetaIntheader value on the response. If the CORS policy does not allow clients to read theIcy-MetaIntheader, thenIcecastMetadataPlayerwill attempt to detect the metadata interval based on the incoming request data.1const player = new IcecastMetadataPlayer("https://stream.example.com/stream.mp3", { 2 onMetadata: (metadata) => {console.log(metadata)}, 3 metadataTypes: ["icy"] 4 ...options 5})
Ogg Metadata
-
Ogg (Vorbis Comment) metadata, if available, usually offers more detail than ICY metadata.
1const player = new IcecastMetadataPlayer("https://stream.example.com/stream.opus", { 2 onMetadata: (metadata) => {console.log(metadata)}, 3 metadataTypes: ["ogg"] 4 ...options 5})
ICY and Ogg Metadata
-
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.
1const player = new IcecastMetadataPlayer("https://stream.example.com/stream.flac", { 2 onMetadata: (metadata) => {console.log(metadata)}, 3 metadataTypes: ["icy", "ogg"] 4 ...options 5})
-
Playing a Stream
-
To begin playing a stream, call the
.play()method on the instance.Note: IcecastMetadataPlayer will use either the MediaSource api or, if that is not available, HTML5 audio with a second request for metadata.
1const player = new IcecastMetadataPlayer("https://stream.example.com/stream.flac", { 2 onMetadata: (metadata) => {console.log(metadata)}, 3 metadataTypes: ["icy"] 4 ...options 5}) 6 7player.play(); -
Metadata will be sent as soon as it is discovered via the
onMetadataEnqueuecallback and when the metadata is synchronized with the audio via theonMetadatacallback. See the Methods section below for additional callbacks.Metadata
1{ 2 StreamTitle: "The stream's title", // ICY 3 StreamUrl: "The stream's url", // ICY 4 TITLE: "The stream's title", // Ogg 5 ARTIST: "The stream's artist", // Ogg 6 ALBUM: "The stream's album" // Ogg 7} -
To stop playing the stream, call the
stop()method on the instance.1player.stop();
See the HTML demos for examples.
Reconnecting
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.
Reconnect Lifecycle:
- The
error/onErrorevent will be fired indicating the issue that caused the retry process to start. - IcecastMetadataPlayer will try to fetch the next stream endpoint periodically using an exponential back-off strategy configurable in the
optionsobject.- Each retry attempt will select the next stream endpoint when a list of stream endpoints are provided. These may be selected in the order they are provided, or in random order. See options.endpointOrder.
- Each retry attempt will fire a
retry/onRetryevent.
- Retries will stop when either of the below conditions are met:
- The fetch request succeeds.
- The audio element is paused /
stop()is called. - The audio element buffer is empty and the retry timeout is met.
- When the retry is successful, a
streamstart/onStreamStartevent will be fired and the audio will restart playing from the new request.- When using the MediaSource API, the old and new request will be synchronized together on a frame basis for seamless playback.
- When the retry times out, a
retrytimeout/onRetryTimeoutevent will be fired and the stream will stop.
Seamless audio playback:
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 be no gap in playback.
To increase the amount of audio that is buffered by clients, increase the <burst-size> setting in your Icecast server.
Switching Endpoints
IcecastMetadataPlayer enables the stream endpoint to be switched during playback to any new endpoint by calling switchEndpoint.
The next endpoint will fetched and attempted to be synchronized with playback from the previous endpoint. The next endpoint is selected from either from the current list of endpoints, or the new passed in list. The transition from the old to new stream should be seamless using synchronization logic that first attempts to match the frame data exactly using CRC32 hashes, and if there is no exact match, by synchronizing the PCM streams using cross-correlation.
switchEndpoint lifecycle
- The old endpoint network request is aborted; however, any buffered audio will continue to play.
- The new endpoint network request is started.
- Playback will attempt to be synchronized with the next endpoint audio using two methods:
- CRC Syncing If the data is an exact match between the old and new endpoints, the stream will be synchronized using CRC32 hashes of each codec frame and playback will continue seamlessly from the new endpoint.
- See codec-parser for the library that enables CRC syncing.
- PCM Syncing If the data does not match, both the old and new audio data will be decoded to PCM and synchronized using a correlation algorithm. The correlation coefficient (-100% worst to 100% best) will be printed to the console if
enableLoggingis set totrue.- See synaudio for the library that enables PCM syncing.
- CRC Syncing If the data is an exact match between the old and new endpoints, the stream will be synchronized using CRC32 hashes of each codec frame and playback will continue seamlessly from the new endpoint.
- Once the new stream is synchronized, playback will begin from the new stream.
- If the buffered audio runs out during synchronization, the new stream will begin to play immediately to prevent any gaps in playback.
API
Methods
-
player.play()async- Plays the Icecast Stream.
- Resolves when the stream begins playing.
-
player.stop()async- Stops playing the Icecast Stream.
- Resolves when the stream has stopped.
-
player.switchEndpoint(endpoints, options)async- Switches to a new stream endpoint and synchronizes the old and new audio.
- See Switching Endpoints for more details. This is meant to be used when switching between streams containing the same audio.
endpointsoptional Single URL or Array of URLs for the new stream endpoint(s). When left empty, and when multiple stream endpoints are present on the instance, the next URL will be selected.optionsoptional Object containing any new options to apply to the instance. All options are allowed except callbacks and the audio element. See options for more details.
- Switches to a new stream endpoint and synchronizes the old and new audio.
-
player.detachAudioElement()- Removes all internal event listeners from the audio element
- Stops audio playback
- Must be called if the audio element is going to be re-used outside of the current instance
-
IcecastMetadataPlayer.canPlayType(mimeType)static- Returns an object
{mediasource, html5, webaudio}containing a string value indicating if passed in mime-type can be played. - Follows the HTML5MediaElement canPlayType() API:
""- Cannot play the codec"maybe"- Might be able to play the codec"probably"- Should be able to play the codec
- Returns an object
Getters
player.audioElement- Returns the HTML5 Audio element.
player.endpoint- Returns the current endpoint being played.
player.icyMetaInt- Returns the ICY Metadata Interval of this instance.
player.metadataQueue- Returns the array of enqueued
metadatain FIFO order.1[ 2 { 3 metadata: { StreamTitle: "Title 1" }, 4 timestampOffset: 2.5, 5 timestamp: 1 6 }, 7 { 8 metadata: { StreamTitle: "Title 2" }, 9 timestampOffset: 5, 10 timestamp: 2 11 } 12]
- Returns the array of enqueued
player.state- Returns the current state of the IcecastMetadataPlayer.
"loading", "playing", "stopping", "stopped", "retrying"
player.playbackMethod- Returns the playback method in use to play the stream.
- The playback method is chosen after the codec of the incoming stream is determined.
"mediasource", "webaudio", "html5"
Instantiating
You can create any number of instances of IcecastMetadataPlayer on your webpage.
Each instance must have it's own audio element.
1const player_1 = new IcecastMetadataPlayer("https://example.com/stream_1", { 2 ...options, 3 ...callbacks 4}); 5 6const player_2 = new IcecastMetadataPlayer("https://example.com/stream_2", { 7 ...options, 8 ...callbacks 9})
Options
endpoints(required)- HTTP(s) endpoint or array of endpoints for the Icecast compatible stream.
- Multiple endpoints can be passed in for client side load balancing or failover.
endpointOrder(optional) - defaultordered- Order to select each endpoint when multiple endpoints are passed in.
- Set to
orderedto select each endpoint in the order they were provided. - Set to
randomto select each endpoint in random order.
audioElement(optional) - Defaultnew Audio()- HTML5 Audio Element to use to play the Icecast stream.
bufferLength(optional) - Default1- Sets the number of seconds to buffer before starting playback
enableLogging(optional) Defaultfalse- Set to
trueto enable warning and error logging to the console
- Set to
enableCodecUpdate(optional) Defaultfalse- Set to
trueto enable thecodecupdateevent. - Codec updates are always enabled if the
onCodecUpdatecallback is present.
- Set to
playbackMethod(optional) Defaultmediasource- Sets the preferred playback method.
"mediasource", "webaudio", "html5" - IcecastMetadataPlayer will attempt to use this playback method first before other methods.
- The playback method is automatically chosen depending on browser support for the codec of the Icecast stream.
- Sets the preferred playback method.
authentication(optional) Default disabled- When supplied, sets the user and password to use when connecting to an authenticated stream.
- This sets the
Authorizationheader in the HTTP request using basic auth. - Example
{user: 'myuser', password: 'mypassword'}
Retry Options
-
retryTimeout(optional) - Default30seconds- Number of seconds to wait before giving up on retries
- Retries are enabled by default, Set to
0to disable retries - Retries will continue until this duration is met AND the audio buffer has been exhausted
(advanced retry logic)
retryDelayMin(optional) - Default0.5seconds- Minimum number of seconds between retries (start of the exponential back-off curve)
retryDelayMax(optional) - Default2seconds- Maximum number of seconds between retries (end of the exponential back-off curve)
retryDelayRate(optional) - Default0.1i.e. 10%- Percentage of seconds to increment after each retry (how quickly to increase the back-off)
Metadata Options
-
metadataTypes(optional) - Default["icy"]- Array containing zero, one, or both metadata types to parse
- Values:
[]- 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
Only used when
["icy"]metadata type is enabledicyMetaInt(optional) Default reads from the response header- ICY Metadata interval read from
Icy-MetaIntheader in the response
- ICY Metadata interval read from
icyCharacterEncoding(optional) Default"uft-8"- Sets the character encoding of the ICY metadata. Most Icecast servers use
utf-8, but encodings such asiso-8859-2are also used. - See Encoding API Encodings for a complete list of character encodings
- Sets the character encoding of the ICY metadata. Most Icecast servers use
icyDetectionTimeout(optional) Default2000- Duration in milliseconds to search for ICY metadata if icyMetaInt isn't passed in
- Set to
0to disable metadata detection
Callbacks (all optional)
Metadata
onMetadata(metadata, timestampOffset, timestamp)Called when metadata is synchronized with the audio.metadataICY or Ogg metadata in an object of key value pairs- ICY:
{ "StreamTitle: "The Stream Title" } - Ogg:
{ "TITLE: "The Stream Title", "ARTIST": "Artist 1; Artist 2"... }
- ICY:
timestampOffsettime in seconds when is scheduled to be updated.timestamptime in seconds when metadata was discovered on the stream.
onMetadataEnqueue(metadata, timestampOffset, timestamp)Called when metadata is discovered on the stream.metadataICY or Ogg metadata in an object of key value pairs- ICY:
{ "StreamTitle: "The Stream Title" } - Ogg:
{ "TITLE: "The Stream Title", "ARTIST": "Artist 1; Artist 2"... }
- ICY:
timestampOffsettime in seconds when is scheduled to be updated.timestamptime in seconds when metadata was discovered on the stream.
Stream lifecycle
onLoad()Called when the fetch request is started.onStreamStart()Called when fetch request begins to return data.onBuffer(time)Called when the audio buffer is being filled.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.
Reconnects
onRetry()Called when a retry / reconnect is attempted.onRetryTimeout()Called when the retry / reconnect attempts have stopped because they have timed-out.
Error / Warning
onWarn(message, ...messages)Called with message(s) when a warning condition is met.onError(message, error)Called with a message and an Error object when an exception occurs when a fallback or error condition is met.
Informational
onCodecUpdate(codecInformation, updateTimestamp)Called with audio codec information whenever there is a change. This callback is synchronized with the audio.codecInformationsuch asbitrateandsamplingRateare passed in as an objectupdateTimestampis the time in seconds within the audio stream when the codec information was updated
Events
Each callback is made available as an event. The parameters for each callback are passed into event.details as an array.
1player.addEventListener('metadata', (event) => { 2 const [metadata, timestampOffset, timestamp] = event.detail; 3})
Troubleshooting
Debugging
Source Map
IcecastMetadataPlayer builds are supplied with a source map, which allows the minified code to be viewed as fully formatted code in a browser debugger.
- To enable the source map, simply copy
icecast-metadata-player-1.17.12.min.js.maplocated in the build folder of this project to the location along sideicecast-metadata-player-1.17.12.min.jsin your website. - The source map can be used to step through and debug the code as well as see the full variable names and file origin on stack traces if you are facing any issues.
Common Issues
ICY Metadata has incorrect characters such as "Zanzibar - Sz�lj M�r" when it should be "Zanzibar - Szólj Már"
- Try setting the
icyCharacterEncodingoption to match the character encoding of the metadata. - A common ICY metadtata encoding other than
utf-8isiso-8859-2
I have an authenticated stream, and when I supply credentials in the
authenticationoption, I get a CORS error.
- Ensure your Icecast server or your proxy has
Authorizationlisted in theAccess-Control-Allow-Headersheader when it responses to the CORSOPTIONSrequest. - Example:
Access-Control-Allow-Headers: Origin, Icy-MetaData, Range, Authorization
Warning messages
Note: Warning messages are be enabled by setting options.enableLogging = true
Reconnected successfully after retry event. Found 145 frames (3.788 seconds) of overlapping audio data in new request. Synchronized old and new request.
- The stream successfully reconnected after a disconnect, and the old request was synchronized with the new request for seamless playback.
- This usually happens when switching networks, or if there was a brief interruption in your internet connection. (i.e. cell to WiFi, WiFi to ethernet, temporary loss of cell connection, etc.)
Reconnected successfully after retry event. Found no overlapping frames from previous request. Unable to sync old and new request.
- The stream successfully reconnected after a disconnect, but there wasn't enough data in the buffer to synchronize the old request with new request.
- If this happens frequently, try increasing the
burst-sizeoption (or equivalent) in your Icecast configuration to increase the client's buffered data.
Passed in Icy-MetaInt is invalid. Attempting to detect ICY Metadata.
- The stream has been requested with ICY metadata, but the server did not respond with the
Icy-MetaIntheader.IcecastMetadataPlayerwill attempt to detect the ICY metadata interval, and will timeout after a default of 2 seconds, or the value in milliseconds passed into theicyDetectionTimeoutoption. - If your stream contains ICY metadata, and it is not detected, audio errors will occur. Increase the detection timeout to search longer for ICY metadata.
- This warning could also be displayed if the stream was requested with ICY metadata, but it does not contain ICY metadata. In this case, the ICY detection will timeout and the stream will play without ICY metadata. Please update your code to no longer request ICY metadata.
This stream is not an Ogg stream. No Ogg metadata will be returned.
- IcecastMetadataPlayer has
"ogg"passed into themetadataTypesoptions, 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.
Error messages
This stream was requested with ICY metadata. If there is a CORS preflight failure, try removing "icy" from the metadataTypes option.
- A network error occurred while requesting the stream with the
Icy-MetaData: 1header.- IcecastMetadataPlayer will attempt to retry the request using the retry configuration.
- It's possible that this was caused by the Icecast server's CORS policy not allowing the
Icy-Metadataheader. If you want ICY metadata, your CORS policy must allow this header to be requested. See CORS Troubleshooting for more information. - Additionally, attempting to access a HTTP from a HTTPS origin will be blocked by modern browsers
Your browser does not support this audio codec mime-type
Unsupported Codec mime-type
- No playback methods are able to play the audio codec being streamed from the Icecast stream. Check the URL that was passed in. If the URL is correct, this stream cannot be played on your browser.
The audio element encountered an error
- An error occurred while the browser was playing or decoding the audio. This may occur if your browser doesn't support a codec or if there is a problem with the Icecast stream.
NotAllowedError: The play method is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.
NotAllowedError: play() failed because the user didn't interact with the document first. https://goo.gl/xX8pDD
No vulnerabilities found.
Reason
binaries present in source code
Details
- Warn: binary detected: src/demo/public/vintage/winamp524_full_emusic-7plus.exe:1
Reason
4 commit(s) and 2 issue activity found in the last 90 days -- score normalized to 5
Reason
Found 0/28 approved changesets -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
license file not detected
Details
- Warn: project does not have a license file
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'main'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 3 are checked with a SAST tool
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
12 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
- Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
- Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
- Warn: Project is vulnerable to: GHSA-4v9v-hfq4-rm2v
- Warn: Project is vulnerable to: GHSA-9jgg-88mc-972h
- Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
- Warn: Project is vulnerable to: GHSA-76p7-773f-r4q5
- Warn: Project is vulnerable to: GHSA-4vvj-4cpr-p986
Score
1.8
/10
Last Scanned on 2025-06-30
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More