DOCSEARCHbyAlgolia
Submit Docs

FCast Documentation

repository·master·Indexed 20 days ago

https://github.com/futo-org/fcast

FCast is an open-source wireless streaming protocol for audio and video (DASH, HLS, mp4) enabling interoperability between senders and receivers across Linux, Windows, MacOS, Android, Tizen OS, and WebOS. The documentation covers the sender-receiver model, reference implementations (Desktop, Terminal, Grayjay), and detailed build instructions for various receiver platforms and the Sender SDK for Kotlin, Swift, and Rust.

Tokens
107K
Snippets
341
Records
479
Agent score
70%

What's inside FCast

  1. What is FCast?

    master
    FCast is an open source protocol designed for the wireless streaming of audio and video content between devices. It supports multiple stream types, including DASH, HLS, and mp4. Unlike proprietary protocols (e.g., Chromecast or AirPlay), FCast is open, allowing developers to build custom receivers or integrate the protocol into existing applications.

  2. Overview of FCast Senders and Receivers

    master

    FCast provides several reference implementations for both sending and receiving content:

    Receivers

    • Android: Receiver implementation for Android devices.
    • Desktop: Receiver implementation for desktop platforms.

    Senders

    • Desktop Sender: Used for mirroring screens or casting multimedia content to FCast receivers.
    • Terminal Sender: A command-line interface (CLI) implementation of the FCast protocol.
    • Grayjay: A multi-platform media application (available on Android and Desktop) that supports FCast.

  4. Add casting capabilities using the FCast SDK

    master
    The FCast SDK allows developers to integrate casting capabilities into their applications. It implements the proprietary FCast protocol and includes support for parts of the Google Cast protocol (specifically the Default Media Receiver).

  5. Supported FCast Sender Applications

    master

    The FCast protocol is supported by several applications for different use cases:

    FUTO Applications

    • Grayjay: A media player that exposes multiple video websites as sources.
    • Terminal: A command-line interface (CLI) sender for controlling FCast via terminal commands.
    • Desktop: A sender for mirroring screens and casting local files from a file system.

    Third-Party Applications

    • CloudStream: An Android app for streaming and downloading media.
    • CastLab: An app for casting gallery media via the DLNA protocol.
    • ReFra: A Jetpack Compose-based media gallery app for Android.

  6. Add casting capabilities using the FCast Sender SDK

    master

    The FCast Sender SDK allows developers to integrate casting functionality into their applications. It is designed to work out of the box with several programming languages, enabling applications to act as senders in the FCast ecosystem.

    Supported languages currently include:

    • Kotlin
    • Swift
    • Rust

    Additional language support is planned for future releases.

  7. What is an FCast Sender?

    master

    An FCast sender is a device or software application responsible for discovering and communicating with an FCast receiver (such as a TV, media top box, or desktop).

    Core Workflow:

    1. Discovery & Connection: The sender discovers a receiver and establishes a connection.
    2. Media Launch: The sender initiates media streaming by launching content on the receiver.
    3. Playback Control: Once media is playing, the sender can perform remote operations including:
      • Pause
      • Resume
      • Seek
      • Volume adjustment

  8. How Screen Mirroring works via WebRTC

    master

    A sender can mirror its screen to a receiver using a WebRTC connection negotiated over the FCast control connection. The sender is the WebRTC offerer and the receiver is the answerer.

    Negotiation Process

    Negotiation is performed using two Flatbuf packets containing MirroringSessionDescription:

    1. Session Initiation: The sender allocates a session_id and sends StartMirroringSession to the receiver.
    2. SDP Offer: The sender gathers ICE candidates (non-trickle) and sends an SDP offer in a MirroringSessionDescription containing the session_id.
    3. SDP Answer: The receiver replies with its own MirroringSessionDescription containing the SDP answer and the same session_id.

    Note: A MirroringSessionDescription with a mismatched session_id is invalid. The reference implementation uses host candidates only (no STUN/TURN), so mirroring is intended for local networks.

  9. Target a receiver by IP or Name

    master

    When using the fcast CLI, you must specify a target receiver. Use one of the following methods:

    • By IP address: Use the -H or --host <ip> flag. If omitted, 127.0.0.1 is assumed.
    • By advertised name: Use the -n or --name <name> flag to target a receiver discovered via mDNS.
    • By name (default): If neither --host nor --name is provided, the client attempts to connect to 127.0.0.1.
    # Target by name
./fcast --name "Living Room TV" play ...

# Target by host IP
./fcast -H 127.0.0.1 play ...

  10. FCast Version 4 Protocol Overview

    master

    FCast Version 4 is a TCP-based protocol running on port 46899. The protocol uses a specific packet structure consisting of a 32-bit Little-Endian (LE) size field, an 8-bit opcode, and a variable-length body.

    Packet Structure

     0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           Size (LE)                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    Opcode     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               :
:                             Body                              :
:                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

    Constraints

    • Size: 32 bits. This value represents the number of bytes following the Size field (Opcode + Body).
    • Opcode: 8 bits.
    • Body Size: Size - 1 (since the opcode is 1 byte).
    • Maximum Packet Size: 512 KiB (total opcode + body).
    • Error Handling: If a party receives a packet where Size = 0 or the size exceeds 512 KiB, it must disconnect immediately.

  11. Use the FCompanion protocol for media transfer

    master

    The FCompanion protocol is used to transfer media data over an FCast connection using a custom binary format (little-endian). Media resources are identified by fcomp:// URLs.

    URL Format: fcomp://<provider-id>.fcast/<resource-id>

    • <provider-id>: A U16 rendered as ASCII decimal digits.
    • <resource-id>: A U32 rendered as ASCII decimal digits.

    Workflow for Senders:

    1. Initialization: Send a CompanionHelloRequest to the receiver.
    2. ID Assignment: The receiver replies with a CompanionHelloResponse containing a provider_id assigned to that specific connection.
    3. URL Construction: Construct fcomp:// URLs using the assigned provider_id and include them in a MediaItem's source_url field.
    4. Data Delivery: When the receiver requests data via CompanionResourceInfoRequest/CompanionResourceRequest, the sender responds with CompanionResourceInfoResponse and Resource packets.

    Note: Receivers must support cases where a sender provides a companion URL belonging to a different connection's provider_id to allow for developer flexibility.

    fcomp://<provider-id>.fcast/<resource-id>

  12. How device state synchronization works

    master

    FCast allows multiple senders to connect to a single receiver. To ensure all connected devices stay in sync (e.g., volume, playback state, track selection), the receiver acts as a relay for state-mutating messages.

    Workflow:

    1. A sender (e.g., S1) sends a mutation message (e.g., VolumeChanged(50%)) to the receiver.
    2. Once the receiver successfully applies the change, it relays that same message to all currently connected senders (including S1).

    Supported synchronized actions include:

    • VolumeChanged
    • Load
    • PlaybackStateChanged
    • SpeedChanged
    • QueueInsert / QueueRemove
    • QueueItemSelected
    • ChangeTrack