ICY-META v2.2 Protocol Specification

Project: Mcaster1DNAS / CasterClub Streaming Standards Initiative (CSSI) Version: 2.2 — March 2026 Maintained By: CasterClub / Mcaster1 Core Team License: Open Spec (CSSI)

Overview

ICY-META v2.2 is an extended streaming metadata protocol built on top of the original SHOUTcast ICY 1.x protocol. It preserves full backwards compatibility with all legacy source encoders and listener clients while adding rich metadata support for modern streaming workflows: live DJ sets, podcasts, video simulcasts, social integration, track-level data, station programming, listener engagement, and content compliance.

The protocol is used by Mcaster1DNAS, mcaster1TagStack, mcaster1DSPEncoder, and mcaster1CastIt, and is published as an open specification by the CasterClub Streaming Standards Initiative (CSSI) for adoption by any streaming platform or client.

All ICY2 fields are optional. Legacy ICY 1.x fields (icy-name, icy-genre, etc.) are never changed, never removed, and always parsed independently of ICY2 logic.

Protocol History

ICY 1.x Legacy Protocol — Full Specification

The original SHOUTcast ICY protocol. These headers, formats, and behaviors are preserved exactly as-is and must never be altered by any ICY2 implementation. Any server claiming ICY2 support must continue to handle ICY 1.x clients without modification.

Source Connection Headers

A source client connects to the server and sends its stream headers before audio data begins. Two connection formats exist:

Format A — SHOUTcast Legacy SOURCE

SOURCE /mountpoint HTTP/1.0
Authorization: Basic c291cmNlOnBhc3N3b3Jk
Content-Type: audio/mpeg
icy-name: My Radio Station
icy-genre: Electronic
icy-url: http://mystation.com
icy-pub: 1
icy-br: 128
icy-metaint: 8192

Format B — Icecast2 / Modern PUT

PUT /mountpoint.mp3 HTTP/1.1
Host: server.example.com:8000
Authorization: Basic c291cmNlOnBhc3N3b3Jk
Content-Type: audio/mpeg
icy-name: My Radio Station
icy-genre: Electronic
icy-url: http://mystation.com
icy-pub: 1
icy-br: 128
icy-metaint: 8192

ICY 1.x Source Headers

Authentication

In-Stream Metadata Block Format

ICY 1.x embeds track title changes directly inside the audio byte stream. Every metaint bytes of audio data, a metadata block is inserted:

# Block length byte = 4  (4 × 16 = 64 bytes total)
# Content (null-padded to 64 bytes):
StreamTitle='Daft Punk - Get Lucky';StreamUrl='';

Only StreamTitle is universally supported. StreamUrl is optional. The full block is always a multiple of 16 bytes, padded with null bytes (\0).

Server Response to Listener

When a listener client connects, the server responds with ICY headers before the audio stream begins:

ICY 200 OK
icy-notice1: SHOUTcast Distributed Network Audio Server
icy-notice2: (c) 1999-2004 Nullsoft, Inc.
icy-name: My Radio Station
icy-genre: Electronic
icy-url: http://mystation.com
icy-pub: 1
icy-br: 128
icy-metaint: 8192
Content-Type: audio/mpeg

[audio stream data with embedded metadata blocks follows]

ICY2 v2.2 — Protocol Detection

A source client signals ICY2 support by including the icy-metadata-version header. The server uses prefix matching — any 2.x value triggers ICY2 parsing. Legacy ICY 1.x fields are still parsed regardless.

icy-metadata-version: 2.2

• Value 2.x (2.0, 2.1, 2.2, etc.) → parse as ICY2
• Header absent or non-2.x → fall back to ICY 1.x parsing only
• ICY2 clients on ICY1 servers: unknown headers are silently ignored

Station Identity

Programming / Show Scheduling

DJ / Host

Track Metadata

Per-track fields pushed on every track change, typically by a metadata injection system (e.g., mcaster1TagStack). icy-meta-track-artwork is the primary field for player album art display.

Podcast

Audio Technical

Reported by source encoders (e.g., mcaster1DSPEncoder). Allows directories and players to display and verify stream quality. icy-meta-loudness uses EBU R128 integrated LUFS measurement.

Video Streaming

Social, Discovery & Branding

Listener Engagement

Broadcast Distribution

icy-meta-crosspost-platforms lists where the content is simultaneously live — distinct from icy-meta-social-youtube which is a static channel profile link.

Station Notices

Real-time listener announcements pushed via the stream for display in ICY2-aware players and notice boards. icy-meta-notice-expires is ISO8601 — players should hide the notice after this time.

Access, Authentication & Compliance

ICY2 v2.1 Backwards Compatibility

The server accepts both the v2.2 icy-meta- prefix and the original v2.1 icy- prefix forms for all ICY2-specific fields. Both always work. Clients should prefer icy-meta- going forward.

Use Cases & Examples

Live DJ Set

icy-metadata-version: 2.2
icy-name: ChillZone FM
icy-genre: Electronic/House
icy-br: 320
icy-pub: 1
icy-meta-station-id: chillzone-fm-001
icy-meta-show-title: Late Night House Sessions
icy-meta-show-start: 2026-02-21T22:00:00Z
icy-meta-show-end: 2026-02-22T02:00:00Z
icy-meta-autodj: 0
icy-meta-dj-handle: @djsynthwave
icy-meta-dj-bio: Berlin-based electronic DJ — deep house, techno, and everything in between.
icy-meta-dj-genre: Electronic, House, Techno
icy-meta-dj-showrating: all-ages
icy-meta-track-artwork: https://cdn.example.com/art/track123.jpg
icy-meta-track-bpm: 124
icy-meta-track-key: 8B
icy-meta-track-mbid: 3a8e7c21-1234-5678-abcd-ef0123456789
icy-meta-audio-codec: mp3
icy-meta-samplerate: 44100
icy-meta-channels: 2
icy-meta-loudness: -14.0
icy-meta-request-enabled: 1
icy-meta-chat-url: https://chillzone.fm/chat
icy-meta-tip-url: https://ko-fi.com/djsynthwave
icy-meta-crosspost-platforms: youtube,twitch
icy-meta-notice: Tune in to our YouTube stream for the video feed tonight!
icy-meta-notice-expires: 2026-02-22T02:00:00Z
icy-meta-nsfw: 0
icy-meta-license-type: pro-licensed

Podcast Episode

icy-metadata-version: 2.2
icy-name: FutureTalks
icy-genre: Talk/Technology
icy-br: 128
icy-pub: 1
icy-meta-station-id: futuretalks-001
icy-meta-show-title: FutureTalks Podcast
icy-meta-podcast-host: Sasha Tran
icy-meta-podcast-rating: all-ages
icy-meta-podcast-episode: S4E1 – Decentralized Rights
icy-meta-podcast-rss: https://futuretalks.fm/feed.xml
icy-meta-duration: 3600
icy-meta-language: en
icy-meta-track-artwork: https://futuretalks.fm/episodes/s4e1.jpg
icy-meta-license-type: cc-by
icy-meta-royalty-free: 1

YouTube Simulcast

icy-metadata-version: 2.2
icy-name: ChillZone FM
icy-meta-videotype: live
icy-meta-videolink: https://youtube.com/watch?v=live543
icy-meta-videotitle: Synthwave All Night
icy-meta-videoplatform: youtube
icy-meta-videoresolution: 1080p
icy-meta-videocodec: h264
icy-meta-videofps: 60
icy-meta-videolive: 1
icy-meta-crosspost-platforms: youtube,twitch
icy-meta-stream-session-id: session-20260221-cz-001

TikTok Short-Form Push (No Audio Needed)

icy-metadata-version: 2.2
icy-name: @DropMaster
icy-meta-videotype: short
icy-meta-videolink: https://tiktok.com/@dropmaster/video/7739201
icy-meta-videochannel: @dropmaster
icy-meta-videoplatform: tiktok
icy-meta-videoposter: https://cdn.tiktok.com/posters/7739201.jpg
icy-meta-videoresolution: 720x1280
icy-meta-duration: 45
icy-meta-emoji: 🎵🔥🎥
icy-meta-hashtag-array: ["#beatdrop","#shorts","#music"]

AutoDJ with Notice

icy-metadata-version: 2.2
icy-name: ChillZone FM
icy-meta-autodj: 1
icy-meta-playlist-name: Top 40 Rotation
icy-meta-next-show: Morning Drive with DJ Kane
icy-meta-next-show-time: 2026-02-22T07:00:00Z
icy-meta-schedule-url: https://chillzone.fm/schedule
icy-meta-notice: Live show starts at 7am — DJ Kane in the morning!
icy-meta-notice-expires: 2026-02-22T07:00:00Z

v2.2 Changelog — What's New

New in v2.2 (from v2.1)

• Prefix standardization: All ICY2 headers now use icy-meta- prefix (v2.1 icy- prefix forms still accepted)
• Track Metadata: icy-meta-track-artwork, track-album, track-year, track-label, track-bpm, track-key, track-genre, track-mbid, track-isrc
• Audio Technical: icy-meta-audio-codec, samplerate, channels, loudness, encoder
• Programming/Show: icy-meta-show-title, show-start, show-end, next-show, next-show-time, schedule-url, autodj, playlist-name
• DJ/Host: icy-meta-dj-handle, dj-bio, dj-genre, dj-showrating
• Listener Engagement: icy-meta-request-enabled, request-url, chat-url, tip-url, events-url
• Broadcast Distribution: icy-meta-crosspost-platforms, stream-session-id, cdn-region, relay-origin
• Station Notices: icy-meta-notice, notice-url, notice-expires
• Licensing: icy-meta-license-type, royalty-free, license-territory
• Video Enhancements: icy-meta-videorating, videocodec, videofps, videoresolution, videonsfw
• Station Identity: icy-meta-station-logo, ssh-pubkey
• Social Expansion: icy-meta-creator-handle, social-twitch, social-youtube, social-facebook-page, social-linkedin

What Changed from v2.1

• All v2.1 headers with icy- prefix remapped to icy-meta- canonical form
• icy-auth-token-key renamed to icy-meta-auth-token
• icy-meta-hashtag-array replaces icy-hashtags (same format)
• icy-meta-ai-generator replaces icy-ai-generated
• v2.1 forms are still parsed — no breaking changes

Integration Targets

• DSPs: SAM Broadcaster, Edcast, BUTT, Rocket Broadcaster, Mixxx
• Admin/GUI: mcasterClient, metadata-pusher agents
• Directory: yp.casterclub.com via /8.json, /status.html, or /push
• Webhook/event-forwarding for real-time content relay

Testing with cURL

Basic ICY 1.x Legacy Test

curl -k -X PUT \
  -H "icy-name: Test Station" \
  -H "icy-genre: Test" \
  -H "icy-url: http://test.example.com" \
  -H "icy-pub: 1" \
  -H "icy-br: 128" \
  -H "Authorization: Basic c291cmNlOnBhc3N3b3Jk" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @audio-file.mp3 \
  https://server.example.com:9443/test.mp3

ICY2 v2.2 Full Test

curl -k -X PUT \
  -H "icy-metadata-version: 2.2" \
  -H "icy-name: Test ICY2 Station" \
  -H "icy-genre: Electronic" \
  -H "icy-br: 128" \
  -H "icy-pub: 1" \
  -H "icy-meta-station-id: test-station-001" \
  -H "icy-meta-show-title: Test Show" \
  -H "icy-meta-autodj: 0" \
  -H "icy-meta-dj-handle: @testdj" \
  -H "icy-meta-track-artwork: https://example.com/art.jpg" \
  -H "icy-meta-track-bpm: 128" \
  -H "icy-meta-audio-codec: mp3" \
  -H "icy-meta-samplerate: 44100" \
  -H "icy-meta-channels: 2" \
  -H "icy-meta-loudness: -14.0" \
  -H "icy-meta-encoder: curl-test/1.0" \
  -H "icy-meta-social-twitter: @teststation" \
  -H "icy-meta-request-enabled: 1" \
  -H "icy-meta-notice: Testing ICY2 v2.2 integration" \
  -H "icy-meta-nsfw: 0" \
  -H "icy-meta-ai-generator: 0" \
  -H "icy-meta-geo-region: GLOBAL" \
  -H "icy-meta-license-type: pro-licensed" \
  -H "Authorization: Basic c291cmNlOnBhc3N3b3Jk" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @audio-file.mp3 \
  https://server.example.com:9443/test.mp3

Full Interactive Specification

For the complete interactive specification with code examples in C, Python, Go, JavaScript, and PHP, plus client integration guides for Winamp, Mixxx, Audacious, iTunes, and Windows Media Player, visit:

ICY-META v2.2 Full Specification

Maintainer Contact

CasterClub Streaming Standards Initiative (CSSI) 📧 specs@casterclub.com 🌐 https://casterclub.com/specs/icy-2 💻 GitHub: https://github.com/casterclub/specs 🪪 License: Open Specification / Attribution Preferred