dart_cast #

Cast media to Chromecast, AirPlay, and DLNA devices from pure Dart.

Features #

• Chromecast (CASTV2) -- TLS + protobuf with default media receiver
• AirPlay -- HTTP video casting with HAP authentication and feature detection
• DLNA/UPnP -- SSDP discovery, SOAP AVTransport control
• Cross-platform -- Android, iOS, macOS, Windows, Linux
• Built-in HTTP proxy -- injects custom headers transparently for cast devices
• HLS rewriting -- rewrites m3u8 playlist URLs through proxy automatically
• Subtitle support -- WebVTT and SRT with automatic SRT-to-VTT conversion
• Local file serving -- serves downloaded content via proxy with MediaTransformer interface
• Pluggable discovery -- swap in native mDNS (e.g., bonsoir) on Apple platforms
• 666+ tests -- mock servers for each protocol

Protocol Status #

Chromecast is the best-tested protocol. For local file casting, remux .ts to .mp4 with ffmpeg. See doc/LOCAL_FILE_CASTING.md.

What Works Where #

Protocol Notes #

Chromecast

• Best overall support; recommended for streaming
• Sidecar VTT subtitles with auto SRT-to-VTT conversion
• Wraps local TS files in HLS via TsHlsMediaTransformer

DLNA

• Best for local/downloaded files
• Uses HTTP/1.0 raw socket server -- Dart's HTTP/1.1 breaks some TVs (e.g., TCL Google TV)
• Embed SRT in MKV for subtitles (most TVs ignore sidecar files)
• TV controls subtitle styling
• HLS piped as TS: works, but reports zero duration and cannot seek
• Local file seeking via byte-range requests (206 Partial Content)

AirPlay

• Video URL casting with V1/V2 auto-negotiation
• Many smart TVs (Google TV, Roku) return 404 on /play -- reliable only on Apple TV
• Screen mirroring and RAOP audio unimplemented

Known Limitations #

• AirPlay video: /play returns 404 on some Google TV devices. Screen mirroring is unimplemented.
• Local TS on Chromecast: TsHlsMediaTransformer has per-segment buffering and subtitle drift. Remux to MP4 via ffmpeg instead -- see example/lib/ffmpeg_media_transformer.dart.
• DLNA streaming: HLS piped as TS works, but reports zero duration and cannot seek.
• DLNA subtitle styling: The TV controls styling, not the app.

Supported Platforms #

Quick Start #

import 'package:dart_cast/dart_cast.dart';

final castService = CastService(
  discoveryProviders: [
    DlnaDiscoveryProvider(),
    ChromecastDiscoveryProvider(),
    AirPlayDiscoveryProvider(),
  ],
  sessionFactory: (device) {
    switch (device.protocol) {
      case CastProtocol.chromecast:
        return ChromecastSession(device: device);
      case CastProtocol.airplay:
        return AirPlaySession(device);
      case CastProtocol.dlna:
        // DLNA requires a device description with control URLs.
        // Use DlnaDeviceDescription.fetch(device) then DlnaSession(device, description).
        return DlnaSession(device, dlnaDescription);
    }
  },
);

// Discover devices on the local network
final devices = await castService.startDiscovery().first;

// Connect to the first device found
final session = await castService.connect(devices.first);

// Cast an HLS stream with custom headers
await session.loadMedia(CastMedia(
  url: 'https://example.com/video.m3u8',
  type: CastMediaType.hls,
  httpHeaders: {'Referer': 'https://example.com'},
  title: 'My Video',
));

// Control playback
await session.pause();
await session.seek(Duration(minutes: 5));
await session.play();

// Monitor state
session.stateStream.listen((state) => print('State: $state'));
session.positionStream.listen((pos) => print('Position: $pos'));

// Clean up
await session.disconnect();
castService.dispose();

API Overview #

CastService #

The main entry point. Manages discovery, connections, and sessions.

final service = CastService(
  discoveryProviders: [...],  // protocol-specific providers
  sessionFactory: (device) => ...,  // creates sessions by protocol
);

• startDiscovery() -- returns a Stream<List<CastDevice>>
• connect(device) -- returns a Future<CastSession>
• reconnect() -- reconnects to the last-used device
• activeSession -- the current session, if any
• dispose() -- releases all resources

CastDevice #

A discovered device on the network.

• id, name -- identity
• protocol -- CastProtocol.chromecast, .airplay, or .dlna
• address, port -- network location
• toJson() / CastDevice.fromJson() -- serialization for persistence

CastSession #

An active connection to a cast device with full playback control.

• loadMedia(CastMedia) -- start playing content
• play(), pause(), stop(), seek(Duration) -- playback controls
• setVolume(double) -- 0.0 to 1.0
• setSubtitle(CastSubtitle?) -- subtitle track selection
• stateStream, positionStream, durationStream, volumeStream -- reactive streams
• disconnect() -- end the session

CastMedia #

Describes what to play.

CastMedia(
  url: 'https://example.com/video.m3u8',
  type: CastMediaType.hls,        // hls, mp4, mkv, or mpegTs
  httpHeaders: {'Referer': '...'}, // injected via proxy
  title: 'Episode 1',
  imageUrl: 'https://example.com/thumb.jpg',
  startPosition: Duration(seconds: 30),
  subtitles: [
    CastSubtitle(
      url: 'https://example.com/subs.vtt',
      label: 'English',
      language: 'en',
      format: 'vtt',
    ),
  ],
);

MediaProxy #

Built-in HTTP proxy that injects headers. Protocol sessions use it internally, but you can use it directly.

• start() / stop() -- lifecycle
• registerMedia(url, headers: {...}) -- returns a proxy URL
• registerFile(filePath) -- serves a local file over HTTP

SubtitleConverter #

Converts between subtitle formats.

• SubtitleConverter.srtToVtt(srtContent) -- convert SRT to WebVTT (for Chromecast)
• SubtitleConverter.vttToSrt(vttContent) -- convert VTT to SRT (for DLNA MKV embedding)
• SubtitleConverter.toAss(content) -- convert to ASS format

DeviceDiscoveryProvider #

Abstract interface for pluggable discovery. Each protocol ships a default implementation; inject alternatives (e.g., bonsoir) on Apple platforms.

Platform Setup #

iOS #

Add to Info.plist:

<key>NSLocalNetworkUsageDescription</key>
<string>This app discovers cast devices on your local network.</string>
<key>NSBonjourServices</key>
<array>
  <string>_googlecast._tcp</string>
  <string>_airplay._tcp</string>
</array>

Android #

Add to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Android 12+ -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" />

macOS #

Add to your entitlements file:

<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.network.server</key>
<true/>

Windows #

No special permissions. Users may need to allow the app through Windows Firewall for proxy and multicast.

How the Proxy Works #

Cast devices cannot send custom HTTP headers (like Referer or cookies) when fetching media. MediaProxy runs a local HTTP server on the device's WiFi IP, rewrites media URLs to route through itself, and forwards requests with the required headers. For HLS streams, it also rewrites segment and variant URLs inside m3u8 playlists so every subsequent request routes through the proxy.

DLNA Local Files #

DLNA local file casting works out of the box -- use CastMedia.file() with CastMediaType.mp4 or .mkv. The proxy serves files over HTTP/1.0 for maximum TV compatibility.

Most DLNA TVs ignore sidecar subtitle URLs. Embed SRT into an MKV container with ffmpeg before casting:

# Remux video + subtitle into MKV (fast, no re-encoding)
ffmpeg -i video.mp4 -i subtitle.srt -map 0 -map 1 -c copy -c:s srt output.mkv

// Cast the MKV with embedded subtitles
await session.loadMedia(CastMedia.file(
  filePath: '/path/to/output.mkv',
  type: CastMediaType.mkv,
  title: 'My Video',
  startPosition: Duration(minutes: 5), // resume from saved position
));

See the example app for a complete implementation with ffmpeg remuxing.

Pluggable Discovery #

The default mDNS discovery uses multicast_dns (pure Dart), which works on Android, Windows, and Linux. On Apple platforms (iOS/macOS), the app sandbox may block raw UDP multicast. Inject a bonsoir-based provider instead:

// In your Flutter app
import 'package:bonsoir/bonsoir.dart';

class BonsoirChromecastProvider implements DeviceDiscoveryProvider {
  @override
  CastProtocol get protocol => CastProtocol.chromecast;

  @override
  Stream<List<CastDevice>> startDiscovery({
    Duration timeout = const Duration(seconds: 10),
  }) {
    // Use BonsoirDiscovery to find _googlecast._tcp services
    // and map them to CastDevice instances.
  }

  // ...
}

final service = CastService(
  discoveryProviders: [BonsoirChromecastProvider()],
  sessionFactory: ...,
);

AirPlay Capabilities #

Feature Flag Detection #

AirPlay devices advertise capabilities as a bitmask in the features (or ft) TXT record. dart_cast parses this during discovery and exposes it via AirPlayFeatures:

final features = AirPlayFeatures.parse('0x5A7FFFF7,0x1E');

features.supportsVideo    // true if bit 0 (V1) or bit 49 (V2) is set
features.supportsScreen   // true if bit 7 is set (screen mirroring)
features.supportsAudio    // true if bit 9 is set (RAOP audio)
features.requiresHapPairing // true if bit 46 or 48 is set
features.isV2Protocol     // true if bit 38 or 48 is set

AirPlay Modes and Current Support #

V1/V2 Auto-Negotiation #

AirPlayMediaController.play() selects the best /play format for the target device:

1. V1 binary plist (application/x-apple-binary-plist) — tried first
2. V1 text/parameters — fallback if V1 plist returns 404 or 415
3. V2 with RTSP SETUP — fallback if V1 text also returns 404 or 415

This negotiation handles the wide variation in third-party AirPlay receivers (Apple TV, smart TVs, audio receivers) without manual configuration.

Devices Without Video Support #

If a device advertises neither video bit (0 nor 49), play() throws UnsupportedFeatureException immediately. Many Google TV / Android TV devices support only screen mirroring, not video URL casting.

try {
  await airPlaySession.loadMedia(media);
} on UnsupportedFeatureException catch (e) {
  // Device supports screen mirroring only — video URL cast not available
  print(e.message);
}

Error Handling #

All exceptions carry a message and optional cause.

Example #

See example/ for a Flutter app with device discovery, connection, and a full remote control UI.

Architecture #

Consumer App (any Dart/Flutter app)
  Uses: CastService, CastSession, CastMedia
          |
Core Layer (protocol-agnostic)
  CastService -> DiscoveryManager
              -> CastSession (state machine)
              -> MediaProxy (header injection)
          |
Protocol Layer (isolated per protocol)
  DLNA         Chromecast       AirPlay
  SSDP         mDNS             mDNS
  SOAP/XML     TLS+Protobuf     HTTP

Acknowledgments and References #

Built with help from these open-source projects, specifications, and community resources:

Protocol References #

• pyatv by Erik Hilsdale -- The most complete open-source Apple TV / AirPlay protocol implementation. Our AirPlay HAP authentication (SRP-6a, pair-setup, pair-verify) is based on pyatv's protocol analysis.
• node-castv2 by Thibaut Séguy -- Reference implementation of the Chromecast CASTV2 protocol. Our protobuf message framing and channel architecture follows this implementation.
• dart_chromecast -- Dart Chromecast implementation that informed our CASTV2 TLS connection and message handling.
• dlna_dart -- Lightweight DLNA client in Dart. Our SSDP discovery and SOAP action patterns were influenced by this package.
• pair_ap by ejurgensen -- C library for AirPlay pairing used by shairport-sync and owntone-server. Referenced for FairPlay-SAP authentication flow details.

Protocol Specifications #

• RFC 8216 -- HTTP Live Streaming (HLS) specification
• RFC 5054 -- SRP-6a protocol and group parameters
• UPnP AV Transport Service -- DLNA/UPnP media control
• Unofficial AirPlay Protocol Specification -- Community-maintained AirPlay reverse engineering docs
• Google Cast Media Messages -- Official Chromecast media protocol documentation
• OpenAirPlay Spec -- AirPlay 2 protocol documentation including HAP pairing

Dart Packages #

• cryptography -- Ed25519, X25519, ChaCha20-Poly1305, HKDF-SHA512 for AirPlay authentication
• multicast_dns -- mDNS service discovery for Chromecast and AirPlay
• protobuf -- Protocol Buffers for Chromecast CASTV2 message serialization
• http -- HTTP client for DLNA SOAP, AirPlay control, and media proxy

Contributing #

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License #

MIT -- see LICENSE for details.