ICY-META v2.2 Protocol Specification

Overview

ICY-META v2.2 is an extended metadata protocol for streaming media servers, providing rich metadata support beyond the legacy ICY 1.x protocol. It maintains backward compatibility while adding modern features for podcasts, video streams, social media integration, track-level metadata, station programming, listener engagement, audio technical parameters, broadcast distribution, and content verification.

Design Principles

1. Backward Compatible — ICY2 clients can connect to ICY1 servers; ICY1 clients can connect to ICY2 servers
2. Zero Configuration — Auto-detection via version header, no server config changes needed
3. HTTP-Based — Pure HTTP header communication, works over HTTP and HTTPS
4. Extensible — Version numbering allows future enhancements (2.2, 2.3, etc.)
5. Optional — All fields are optional; only send what’s relevant

Protocol Detection

Version Header

The presence of the icy-metadata-version header indicates ICY2 support:

icy-metadata-version: 2.1

Server Behavior:

• If header present with value 2.x → Parse as ICY2
• If header absent or invalid → Fall back to ICY 1.x legacy parsing
• Version check uses prefix matching (2. matches 2.0, 2.1, 2.2, etc.)

Client Handshake

ICY2-compliant source clients send this header with their source PUT/POST request:

PUT /mountpoint.mp3 HTTP/1.1
Host: server.example.com:9443
icy-metadata-version: 2.2
icy-meta-station-id: unique-station-identifier
icy-name: My Station Name
icy-genre: Electronic
icy-br: 128
icy-pub: 1
Authorization: Basic c291cmNlOnBhc3N3b3Jk
Content-Type: audio/mpeg

[audio data]

ICY 1.x Legacy Headers

These are the original SHOUTcast/Icecast ICY protocol headers. They are never modified, never removed, and are always parsed independently of any ICY2 logic. ICY2 fields are additional — these remain exactly as they have always been for full backwards compatibility.

Legacy auth fields (also unchanged):

ICY2 v2.1 Header Forms (Backwards Compatible)

These are the original ICY2 v2.1 header names as implemented in the server’s C source (icy2_meta_parse_headers()). They use the icy- prefix without meta. The server continues to accept these from any client that connected using the v2.1 format.

Field Reference (v2.2)

Station Identity

Programming / Show

DJ / Host

Track Metadata

Podcast

Video

Audio Technical

Social

Listener Engagement

Broadcast Distribution

Station Notices

Access & Authentication

Content Flags & Compliance

Server Implementation

Detection Logic

// Check for ICY2 version header
const char *version = httpp_getvar(parser, "icy-metadata-version");
if (version && strncmp(version, "2.", 2) == 0) {
    // Parse as ICY2
    icy2_metadata *meta = icy2_meta_new();
    icy2_meta_parse_headers(meta, parser);
    icy2_meta_copy_to_stats(meta, source->stats);
    icy2_meta_free(meta);
} else {
    // Fall back to ICY 1.x legacy parsing
    parse_legacy_icy_headers(parser);
}

Parser Implementation Notes

The v2.2 parser accepts both icy-meta-X (spec-compliant) and legacy icy-X (v2.1 clients) header forms during the migration period. Try icy-meta-X first; fall back to icy-X:

/* Example: station-id -- try spec-compliant prefix first, fall back for v2.1 clients */
str = httpp_getvar(parser, "icy-meta-station-id");
if (!str) str = httpp_getvar(parser, "icy-station-id");
if (str) meta->station_id = icy2_strdup_safe(str);

Version History

Client Best Practices

1. Always include icy-metadata-version — this triggers ICY2 parsing
2. Use consistent station-id — helps with stream tracking and analytics
3. Provide social media handles — enhances discoverability
4. Set appropriate content flags — NSFW, AI-generated for transparency
5. Include video metadata if streaming video alongside audio
6. Use emoji sparingly — 2–5 emoji max for UI enhancement
7. Validate URLs — ensure all URL fields are properly formatted
8. Keep hashtags relevant — 3–10 hashtags, space or comma-separated

License & Attribution

Copyright © 2026 David St John (Saint John) — MediaCast1 / Mcaster1DNAS Project.
Released under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
Implementation in Mcaster1DNAS is licensed under GNU GPL v2.