How It Works

Binary Protocol

File data is sent as FILE_CHUNK messages (type 0x13) on the data channel, while metadata (file list, hash results, progress) flows as JSON on the control channel:

The 11-byte header identifies which file and chunk position each message belongs to, enabling concurrent transfers and out-of-order reassembly.

Streaming Reads

The host never loads an entire file into memory. Instead, each 14KB chunk is read on-demand using File.slice():

• • Only the current chunk occupies memory at any time
• • Enables sharing files of any size without memory constraints

Download Strategies

The receiver selects the best available download method based on browser capabilities:

Integrity Verification

SHA-256 hashes are computed for each file and shared with recipients:

• • Hashing runs in a Web Worker using the hash-wasm library
• • Incremental/streaming hashing - never loads the full file into memory
• • Recipients can view the hash for manual verification if preferred
• • After download, the received file's hash is compared to verify integrity

Safety Features

• • Executable warning: Alert shown before downloading potentially dangerous files (.exe, .bat, .msi, .dmg, .sh, etc.)
• • Filename sanitization: Prevents path traversal, hidden files, reserved names, and non-ASCII issues
• • Per-peer isolation: Each recipient has independent transfer state
• • SVG safety: SVGs rendered via <img> tags only - embedded scripts are neutralized

Dual Channel Architecture

Two separate data channels serve different purposes:

Flow Control

Data channels have limited buffer capacity. Exceeding it can crash the browser. SpectrShare implements strict flow control:

Before every send operation, the current buffer level is checked. If it exceeds 60% of capacity, the message is queued instead of sent. When the buffer drains to the low threshold, queued messages are processed.

Request Queue System

The host maintains a per-peer request queue to prevent one slow recipient from blocking others:

• • Each recipient has an independent queue
• • Maximum 2 concurrent requests in flight per peer
• • Request timeout: 15 seconds with up to 3 retry attempts
• • Incomplete chunk data cleaned up after 30 seconds

Strategy Selection

SpectrShare selects the optimal processing method based on browser capabilities:

• Hardware-accelerated (primary) - Uses the WebCodecs API via the Mediabunny library for GPU-accelerated encoding and decoding. Processes a typical 1-hour video in minutes.
• Software fallback - Uses FFmpeg compiled to WebAssembly when WebCodecs is unavailable or fails. Comprehensive format support but significantly slower (CPU-bound and single threaded).

For incompatible audio codecs (E-AC3, AC3, DTS), only the audio track is transcoded while video is remuxed directly.

Output Format: H.264 Baseline

All video is encoded to H.264 Baseline Profile Level 4.1 for maximum compatibility:

• • H.264 Baseline Profile provides maximum device compatibility
• • Level 4.1 enables 1080p @ 30fps playback
• • AAC-LC at 48kHz for universal audio support

Segmentation

The encoded video is split into independently-decodable segments:

• • 3-second segments balance seeking granularity with network efficiency
• • Each segment begins with a keyframe (required for independent decoding)
• • Fragmented MP4 format: initialization segment (ftyp/moov boxes) plus media segments (moof/mdat boxes)

Progressive Storage & Bundles

Segments are written to the browser's Cache API immediately as they're processed, rather than accumulated in memory. This prevents memory exhaustion when processing long videos.

Processed videos can be downloaded as a .pvs bundle containing all segments, initialization data, and timestamps. These bundles enable re-sharing without re-processing.

Background Processing

Video conversion runs after sharing begins - files are immediately available for download while conversion happens in the background. Multiple video files are processed sequentially (one at a time) to avoid exhausting browser memory. Each file can be individually cancelled. When conversion completes, connected recipients are notified automatically and can start streaming.

MediaSource Extensions (MSE)

MSE is a browser API that enables programmatic feeding of media data to a video element:

• • An initialization segment is appended first (contains codec parameters)
• • Media segments are appended to a SourceBuffer for playback
• • The browser handles decoding, rendering, and audio/video synchronization
• • Each quality level has its own initialization segment

Buffer Management

The viewer maintains a forward buffer for uninterrupted playback:

Buffer targets are automatically reduced when device memory is constrained. In emergency mode (>90% heap usage), buffer drops to 22% of normal size.

Accurate Seeking

Segment durations can vary slightly due to keyframe alignment. SpectrShare maintains a mapping of segment start times:

• • An array stores the actual cumulative start time of each segment
• • Binary search (O(log n)) finds the segment containing any target time
• • This ensures accurate seeking even for multi-hour videos
• • Each segment begins with a keyframe for clean decode at any position

Quality Switching

When a recipient selects a different quality level:

1. All pending requests for the old quality are cancelled
2. The new quality's initialization segment is fetched
3. The SourceBuffer is reset with new codec parameters
4. Segment loading resumes at the current timestamp
5. Playback continues with minimal interruption

Direct P2P Connection

When network conditions permit, a direct connection is established using STUN for NAT traversal. You can test your connectivity to check your NAT type. All data flows directly between browsers.

TURN Relay (Fallback)

When direct connections fail (corporate firewalls, symmetric NAT), data is relayed through a TURN server. TURN is disabled by default and must be explicitly enabled.

Password Protection

Hosts can enable optional password protection on share sessions. This uses a challenge-response mechanism to ensure only recipients with the correct password can access the files.

The actual password is never transmitted over the network. Even if the signaling channel were monitored, the password cannot be derived from the exchanged hashes.

After Connection Establishment

Once the WebRTC connection is established, all data flows directly between browsers. The signaling server is only involved in the initial handshake and is never in the data path.

FFmpeg (LGPL-2.1+)

The optional video conversion fallback uses ffmpeg.wasm, a WebAssembly port of FFmpeg. FFmpeg is licensed under the GNU Lesser General Public License v2.1 or later.

FFmpeg source code is available at github.com/FFmpeg/FFmpeg. The ffmpeg.wasm build used here is unmodified from the upstream release.

Mediabunny (MPL-2.0)

The primary video conversion path uses Mediabunny, a pure TypeScript media toolkit licensed under the Mozilla Public License 2.0.