4.5 KiB

Raw Blame History

NIP-XX

Internet Radio

draft optional

This NIP defines a standard for publishing and discovering internet radio stations on Nostr, enabling decentralized radio station directories, streaming metadata, social features, and interoperability between radio applications.

Radio Station Events

Radio stations are published as addressable events of kind:31237. These events contain streaming URLs, metadata, and technical specifications needed for playback.

Event Structure

{
  "kind": 31237,
  "content": "<JSON metadata>",
  "tags": [
    ["d", "<station-identifier>"],
    ["name", "<station-name>"],
    ["t", "<genre>"],
    ["l", "<ISO-639-1-code>"],
    ["countryCode", "<ISO-3166-2-code>"],
    ["location", "<human-readable-location>"],
    ["g", "<geohash>"],
    ["thumbnail", "<image-url>"],
    ["website", "<station-website>"]
  ]
}

Content Format

The content field MUST contain a JSON string with the following structure:

{
  "description": "Station description with **markdown** support",
  "streams": [
    {
      "url": "https://stream.example.com/radio.mp3",
      "format": "audio/mpeg",
      "quality": {
        "bitrate": 128000,
        "codec": "mp3",
        "sampleRate": 44100
      },
      "primary": true
    }
  ],
  "streamingServerUrl": "https://server.example.com"
}

Required Fields

description: Human-readable description (markdown supported)
streams: Array of stream objects (minimum one required)

Optional Fields

streamingServerUrl: Base URL of the streaming server (needed for metadata endpoints when using typical streaming servers like Icecast that provide /status-json.xsl, /admin/stats, or similar metadata APIs)

Stream Object

Each stream object MUST include:

url: Direct URL to the audio stream
format: MIME type (e.g., "audio/mpeg", "audio/aac")
quality: Object with bitrate, codec, and sampleRate
primary: Boolean indicating the default stream (optional)

Required Tags

d: Unique identifier for the station (used for addressability)
name: Human-readable station name

Recommended Tags

t: Genre/category tags (multiple allowed)
l: ISO 639-1 language codes (multiple allowed)
countryCode: ISO 3166-2 country code
location: Human-readable location string
g: Geohash for precise geographical coordinates
thumbnail: Station logo/image URL
website: Station's official website

Example

{
  "kind": 31237,
  "pubkey": "a1b2c3d4...",
  "created_at": 1690000000,
  "content": "{\"description\":\"Eclectic mix of jazz, world music, and electronic sounds from France.\",\"streams\":[{\"url\":\"https://icecast.radiofrance.fr/fiprock-hifi.aac\",\"format\":\"audio/aac\",\"quality\":{\"bitrate\":128000,\"codec\":\"aac\",\"sampleRate\":44100},\"primary\":true}]}",
  "tags": [
    ["d", "a7f9d2e1b8c3"],
    ["name", "FIP Radio"],
    ["t", "jazz"],
    ["t", "world"],
    ["t", "electronic"],
    ["l", "fr"],
    ["countryCode", "FR"],
    ["location", "Paris, France"],
    ["g", "u09tvw0"],
    ["thumbnail", "https://example.com/fip-logo.png"],
    ["website", "https://www.radiofrance.fr/fip"]
  ]
}

Radio stations can leverage existing Nostr social protocols:

Live Chat Messages

Real-time chat during radio streaming uses existing live chat protocols such as NIP-53. Messages should reference the radio station via a tag to associate chat with the specific station.

Station Comments

Persistent discussion threads use existing comment protocols such as NIP-22. Comments should reference the radio station event to create threaded discussions about stations.

Implementation Notes

Station Identification

The d tag value SHOULD be a random identifier to ensure stability over time
If no d tag is present, it defaults to an empty string
Multiple stations can be published by the same pubkey using different d tags

Streaming Compatibility

Support multiple stream formats for broader client compatibility
Include quality metadata to enable adaptive streaming
Mark one stream as primary for default selection

Content Indexing

Use t tags for genre/category filtering
Include l tags for internationalization
Add g tags with geohash for precise geographical discovery

Reference Implementation

A reference implementation is available at WaveFunc, demonstrating station publishing, favorites management, and social features.

4.5 KiB Raw Blame History