ICY Metadata Reference

TagStack supports both ICY protocol versions. ICY 1.x is the simple, universally compatible now-playing title push. ICY 2.2 is the full extended metadata specification with 90+ structured header fields.

ICY 1.x — Now Playing Title Push

ICY 1.x sends a plain-text stream title via a GET request to the admin endpoint. Every Icecast2 and Mcaster1DNAS server supports this.

Endpoint

GET /admin/metadata?mount=/yourmount&mode=updinfo&song=Artist+-+Track+Title
Authorization: Basic base64(admin:adminpassword)

Rules

• The song parameter is URL-encoded (spaces become + or %20). TagStack uses libcurl's curl_easy_escape automatically.
• Conventional format: Artist - Track Title (separated by a space-dash-space).
• Maximum recommended length: 255 characters.
• To clear now-playing (show station name only), push an empty song string.

ICY 2.2 — Extended Metadata Headers

ICY 2.2 sends a structured set of HTTP headers via a PUT request to the source mount. TagStack builds the full header set from the 4-tab composer and sends only the non-empty fields to avoid noise.

Push Endpoint

PUT /yourmount HTTP/1.1
Host: dnas.example.com:8000
Authorization: Basic base64(source:sourcepassword)
Content-Type: audio/mpeg
Content-Length: 0
icy-metadata-version: 2.2
icy-meta-station-id: my-station-001
icy-meta-show-title: Morning Drive
icy-meta-dj-handle: @djname
icy-meta-social-twitter: @djname
...

ICY 2.2 Field Reference

Tab 1 — Station / Show

Tab 2 — DJ / Track

Tab 3 — Social

Tab 4 — Broadcast

Practical Push Examples

Minimum push for a live DJ set

icy-metadata-version: 2.2
icy-meta-station-id: wkrp-001
icy-meta-show-title: Friday Night Bass
icy-meta-dj-handle: @djace
icy-meta-genre: House
icy-meta-bpm: 128
icy-meta-social-twitter: @djace
icy-meta-social-ig: @djace
icy-meta-hashtag-array: ["#FridayNight","#House","#DJSet"]

Full station identity push

icy-metadata-version: 2.2
icy-meta-station-id: wkrp-cincinnati-001
icy-meta-station-logo-url: https://wkrp.com/logo.png
icy-meta-station-verified: verified
icy-meta-show-title: Morning Drive
icy-meta-show-start: 06:00
icy-meta-show-end: 10:00
icy-meta-next-show: Midday Mix
icy-meta-dj-handle: @djace
icy-meta-genre: Top 40
icy-meta-social-twitter: @wkrp
icy-meta-social-ig: @wkrpcincinnati
icy-meta-social-tiktok: @wkrp
icy-meta-social-youtube: https://youtube.com/@wkrp
icy-meta-social-facebook-page: https://facebook.com/wkrpcincinnati
icy-meta-audio-codec: MP3
icy-meta-audio-samplerate: 44100
icy-meta-audio-channels: 2
icy-meta-audio-lufs: -14

Best Practices

• Push ICY 2.2 at the start of every show and whenever the track changes.
• Use the icy-meta-hashtag-array field as a proper JSON array — TagStack validates the format before sending.
• Set icy-meta-bpm and icy-meta-key accurately — ICY 2.2-aware players and future Mcaster1 features will use these for harmonic mixing and energy profiling.
• Include icy-meta-track-artwork-url — many players and web widgets display this art as the album cover.
• Only non-empty fields are sent in the PUT request. Leave fields blank in the composer if they are not relevant to the current show.