Superstreamer Documentation

The @superstreamer/player package provides a high-quality video player built using React and Tailwind CSS. It is a core component of the Superstreamer ecosystem, designed to handle adaptive video playback as part of an end-to-end streaming toolkit.

For detailed implementation guides and a live interactive demo, visit the official documentation: https://matvp91.github.io/superstreamer/guide/player.html

Superstreamer is a self-hostable platform designed to simplify video delivery. It provides tools for:

• Transcoding: Convert video files into multiple quality tracks (e.g., 1080p, 720p, 480p).
• Packaging: Write HLS CMAF playlists directly to S3 for streaming.
• Dynamic Stitching: Create HLS interstitials on the fly to insert bumpers (like Netflix-style intros) or ads.
• Ad Insertion: Support for linear ads via VMAP or manual VAST scheduling.
• Player Integration: A player facade that provides a simplified API alongside HLS.js, specifically designed for developers building custom player UIs.

The @superstreamer/player package acts as a wrapper around HLS.js, providing a simplified API for developers building player UIs. Key features include:

• Intuitive API: Data structures, events, and methods tailored for UI development.
• State Management: A robust internal state machine.
• Simplified Methods: Player-centric commands like playOrPause and setVolume.
• Plugin Support: Support for spec-compliant plugins, including ad signaling.

The core workflow in Superstreamer involves getting video into the system, which typically follows these steps:

1. Upload: Provide a video file to the system.
2. Transcode: Instruct Superstreamer to transcode the video into multiple quality tracks.
3. Package: Package the transcoded tracks into a format compatible with video players (e.g., HLS).

You can manage this workflow using the API or via the Dashboard.

The Superstreamer backend consists of three primary services that handle job scheduling, execution, and playlist manipulation:

• API: The primary interface for interacting with the system. It is used to start tasks like transcoding or packaging jobs. It exposes an OpenAPI specification at the /openapi endpoint.
• Artisan: The background job runners. Artisan consumes jobs scheduled by the API, instructs ffmpeg to run transcoding tasks, or packages transcoded assets into HLS playlists and syncs them to S3.
• Stitcher: A "playlist manipulator" service with its own API (also exposing /openapi). It can create user-specific sessions to generate custom HLS playlists, enabling features like resolution filtering and the insertion of bumpers or linear ads.

The Superstreamer frontend ecosystem provides tools for management and playback:

• App: A Single Page Application (SPA) designed to interact with the API or initiate sessions on the Stitcher service.
• Player: A facade that simplifies HLS.js. It provides an intuitive API for building players, supports plugins, and includes React hooks for efficient state management.

The @superstreamer/stitcher package is a real-time playlist manipulator. It is designed to proxy HLS (HTTP Live Streaming) playlists and perform on-the-fly manipulations, such as inserting interstitials.

Key capabilities include:

• Master Playlist Filtering: The ability to filter content within the master playlist.
• Ad Insertion: It can resolve VMAP or VAST specifications and automatically inject the resulting ads as part of an interstitial stream.

Stitcher provides several advanced HLS manipulation capabilities:

• Manual Interstitial Insertion: Provide a specific asset (like a Netflix bumper) or a VAST URL for ad insertion.
• VMAP Transformation: Automatically transforms a VMAP into HLS interstitials at the correct positions within the stream.
• Ad Signaling Support: Inserts interstitials based on existing ad signaling in the playlist, such as EXT-X-CUE-OUT tags.
• Live and VOD Support: Capable of personalizing both live and Video-on-Demand (VOD) playlists.
• Region Replacement: Replace specific regions in a stream with personalized playlists.
• Track Filtering: Ability to filter renditions, text tracks, subtitle tracks, and more.

Superstreamer provides tools for several distinct stages of the video lifecycle:

• Transcoding: Adjusting video quality and formats to ensure smooth playback across different devices and unpredictable internet bandwidths.
• Packaging: Preparing video files for smooth streaming to viewers globally.
• Stitching:
  • Monetization: Performing on-the-fly ad insertion.
  • Playout Filtering: Filtering quality and text tracks by language to tailor content for specific audiences.
• Client-side Playback: Using the player facade to simplify integration with HLS.js, avoiding the complexity of low-level video library code.

Stitcher is a separate project within the Superstreamer ecosystem designed as an HLS playlist manipulator. It allows for on-the-fly insertion of interstitials into HLS streams.

Key use cases include:

• Ad Insertion: Inserting advertisements via VAST URLs or manual assets (e.g., brand bumpers).
• Personalization: Replacing specific regions in a stream (like ad breaks in a live-to-vod scenario) with personalized playlists.
• User-Specific Constraints: Setting individual quality limits for different users.
• Stream Manipulation: Filtering renditions, text tracks, and subtitle tracks.