Gathering detailed insights and metrics for icecast-metadata-player
Gathering detailed insights and metrics for icecast-metadata-player
Gathering detailed insights and metrics for icecast-metadata-player
Gathering detailed insights and metrics for icecast-metadata-player
npm install icecast-metadata-player
Typescript
Module System
Node Version
NPM Version
76
Supply Chain
96.3
Quality
85.4
Maintenance
100
Vulnerability
77.3
License
icecast-matadata-player/1.17.9
Published on 15 Dec 2024
icecast-metadata-player/1.17.8
Published on 15 Dec 2024
icecast-metadata-player/1.17.7
Published on 10 Dec 2024
icecast-metadata-player/1.17.6
Published on 15 Nov 2024
icecast-metadata-player/1.17.5
Published on 15 Nov 2024
icecast-metadata-stats/0.1.12
Published on 14 Nov 2024
JavaScript (69.06%)
HTML (29.31%)
CSS (1.21%)
XSLT (0.42%)
Total Downloads
54,193
Last Day
182
Last Week
736
Last Month
2,033
Last Year
28,113
176 Stars
480 Commits
20 Forks
9 Watching
5 Branches
2 Contributors
Minified
Minified + Gzipped
Latest Version
1.17.9
Package Id
icecast-metadata-player@1.17.9
Unpacked Size
1.40 MB
Size
657.26 kB
File Count
32
NPM Version
9.6.7
Node Version
18.17.1
Publised On
15 Dec 2024
Cumulative downloads
Total Downloads
Last day
55.6%
182
Compared to previous day
Last week
7.4%
736
Compared to previous week
Last month
43.4%
2,033
Compared to previous month
Last year
87.9%
28,113
Compared to previous year
Icecast Metadata Player is browser library that plays streaming audio with full cross-platform codec support and real-time metadata updates.
<script>
tag.
See the main page of this repo for other Icecast JS tools: https://github.com/eshaz/icecast-metadata-js
audio/mpeg
, audio/mp4
audio/aac
, audio/mp4
audio/flac, application/ogg
, audio/mp4
application/ogg
, audio/mp4
, audio/webm
application/ogg
, audio/webm
npm i icecast-metadata-player
Example
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);
Download all of the files here for the latest build and save these to a path on your server.
*.js
files must be saved into the same path on your server.*.js.map
files are optional source maps for debugging.
Filename | Functionality |
---|---|
icecast-metadata-player-1.17.9.main.min.js | Core functionality (playback, metadata) Use this file in your <script> tag |
icecast-metadata-player-1.17.9.synaudio.min.js | Gapless playback support |
icecast-metadata-player-1.17.9.mediasource.min.js | Mediasource playback support |
icecast-metadata-player-1.17.9.mpeg.min.js | MPEG playback support (webaudio) |
icecast-metadata-player-1.17.9.flac.min.js | FLAC playback support (webaudio) |
icecast-metadata-player-1.17.9.opus.min.js | Opus playback support (webaudio) |
icecast-metadata-player-1.17.9.vorbis.min.js | Vorbis playback support (webaudio) |
icecast-metadata-player-1.17.9.common.min.js | Common functions (webaudio) |
Add a <script>
tag referencing icecast-metadata-player-1.17.9.main.min.js
in your html.
IcecastMetadataPlayer
is made available as a global variable in your webpage to use wherever.
Example
1<script src="icecast-metadata-player-1.17.9.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>
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 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.
1const player = new IcecastMetadataPlayer("https://stream.example.com/stream.mp3", { 2 onMetadata: (metadata) => {console.log(metadata)}, 3 metadataTypes: ["icy"] 4 ...options 5})
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 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})
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 onMetadataEnqueue
callback and when the metadata is synchronized with the audio via the onMetadata
callback. See the Methods section below for additional callbacks.
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.
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.streamstart
/ 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 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.
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
lifecycleenableLogging
is set to true
.
player.play()
async
player.stop()
async
player.switchEndpoint(endpoints, options)
async
endpoints
optional 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.options
optional 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.player.detachAudioElement()
IcecastMetadataPlayer.canPlayType(mimeType)
static
{mediasource, html5, webaudio}
containing a string value indicating if passed in mime-type can be played.""
- Cannot play the codec"maybe"
- Might be able to play the codec"probably"
- Should be able to play the codecplayer.audioElement
player.endpoint
player.icyMetaInt
player.metadataQueue
metadata
in 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]
player.state
"loading", "playing", "stopping", "stopped", "retrying"
player.playbackMethod
"mediasource", "webaudio", "html5"
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})
endpoints
(required)
endpointOrder
(optional) - default ordered
ordered
to select each endpoint in the order they were provided.random
to select each endpoint in random order.audioElement
(optional) - Default new Audio()
bufferLength
(optional) - Default 1
enableLogging
(optional) Default false
true
to enable warning and error logging to the consoleenableCodecUpdate
(optional) Default false
true
to enable the codecupdate
event.onCodecUpdate
callback is present.playbackMethod
(optional) Default mediasource
"mediasource", "webaudio", "html5"
authentication
(optional) Default disabled
Authorization
header in the HTTP request using basic auth.{user: 'myuser', password: 'mypassword'}
retryTimeout
(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 responseicyCharacterEncoding
(optional) Default "uft-8"
utf-8
, but encodings such as iso-8859-2
are also used.icyDetectionTimeout
(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 in seconds when is scheduled to be updated.timestamp
time in seconds 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 in seconds when is scheduled to be updated.timestamp
time in seconds when metadata was discovered on the stream.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.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, error)
Called with a message and an Error object when an exception occurs when a fallback or error condition is met.onCodecUpdate(codecInformation, updateTimestamp)
Called with audio codec information whenever there is a change. This callback is synchronized with the audio.
codecInformation
such as bitrate
and samplingRate
are passed in as an objectupdateTimestamp
is the time in seconds within the audio stream when the codec information was updatedEach 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})
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.17.9.min.js.map
located in the build folder of this project to the location along side icecast-metadata-player-1.17.9.min.js
in your website.ICY Metadata has incorrect characters such as "Zanzibar - Sz�lj M�r" when it should be "Zanzibar - Szólj Már"
icyCharacterEncoding
option to match the character encoding of the metadata.utf-8
is iso-8859-2
I have an authenticated stream, and when I supply credentials in the
authentication
option, I get a CORS error.
Authorization
listed in the Access-Control-Allow-Headers
header when it responses to the CORS OPTIONS
request.Access-Control-Allow-Headers: Origin, Icy-MetaData, Range, Authorization
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.
Reconnected successfully after retry event. Found no overlapping frames from previous request. Unable to sync old and new request.
burst-size
option (or equivalent) in your Icecast configuration to increase the client's buffered data.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.This stream was requested with ICY metadata. If there is a CORS preflight failure, try removing "icy" from the metadataTypes option.
Icy-MetaData: 1
header.
Icy-Metadata
header. If you want ICY metadata, your CORS policy must allow this header to be requested. See CORS Troubleshooting for more information.Your browser does not support this audio codec mime-type
Unsupported Codec mime-type
The audio element encountered an error
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
12 commit(s) and 7 issue activity found in the last 90 days -- score normalized to 10
Reason
binaries present in source code
Details
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
Reason
license file not detected
Details
Reason
project is not fuzzed
Details
Reason
branch protection not enabled on development/release branches
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
Reason
22 existing vulnerabilities detected
Details
Score
Last Scanned on 2025-01-27
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