# StudioSwarm Full System Documentation & Technical Reference Version: 1.0.0 Author: StudioSwarm Open-Source Engineering Team License: MIT Primary Architecture: WebRTC + File System Access API + Stateless Zero-Knowledge Tracker --- ## 1. Executive Summary & Purpose StudioSwarm solves the single largest pain point in modern film, video, and content creation: the delay, cost, and security vulnerabilities associated with transferring multi-gigabyte and multi-terabyte raw media files (Apple ProRes 422/4444, Blackmagic RAW, REDCODE RAW, Sony XAVC, ARRIRAW) and NLE project files (Adobe Premiere Pro, DaVinci Resolve, Final Cut Pro) across distributed teams. Instead of uploading 100 GB to Amazon S3, Dropbox, WeTransfer, or Frame.io, waiting 2 to 4 hours, and paying steep egress and storage tiers ($15–$50/user/month), StudioSwarm establishes direct peer-to-peer WebRTC SCTP connections between creator workstations. Files stream directly from sender SSD to recipient SSD at full internet line speed (up to 120+ MB/s) with end-to-end AES-GCM-256 encryption. --- ## 2. Technical Architecture ### 2.1 WebRTC Transport Layer (`src/core/webrtc-transport.ts`) - **4-Lane Multipath SCTP Striping**: Spawns 4 parallel unordered `RTCDataChannel` lanes per peer connection (`studioswarm-lane-0` through `studioswarm-lane-3`). Slices 16 MB piece ciphertexts into 64 KB binary frames and stripes them in round-robin fashion, eliminating Head-of-Line (HoL) blocking on single data channels. - **Shortest-Queue-First (SQF) Adaptive Congestion Routing**: Continuously monitors `bufferedAmount` on each lane. If a lane becomes congested, traffic dynamically routes to clear lanes. - **Zero-Copy TurboSwarm Binary Framing**: 69-byte binary header followed directly by raw encrypted chunk bytes, bypassing 33% Base64 payload bloat. ### 2.2 Storage & File System Engine (`src/core/storage-engine.ts`) - **Direct-to-Disk Streaming via File System Access API**: Uses `window.showDirectoryPicker` and `FileSystemWritableFileStream` to write binary pieces directly to physical disk offsets (`writable.seek() + writable.write()`). Keeps JavaScript heap memory usage at O(1) (< 120 MB RAM) even when transferring 150 GB folders. - **OPFS Fallback**: Uses Origin Private File System (`navigator.storage.getDirectory()`) on Firefox and Safari. - **NLE Project Delta History**: Automatically creates timestamped non-destructive snapshots of `.prproj` and `.drp` files inside `.swarm-history/` upon detecting changes. ### 2.3 Cryptographic Security Model (`src/core/crypto-e2ee.ts`) - **AES-GCM-256 Symmetric Encryption**: Each Swarm Room generates a random 256-bit AES key. Every 16 MB piece is encrypted with a fresh 12-byte cryptographically secure IV (`crypto.getRandomValues`) and verified with an authentication tag and SHA-256 integrity hash. - **URL `#` Hash Fragment Key Isolation**: Room decryption keys are strictly isolated in the URL fragment (`/#r=&k=`). Per RFC 3986, web browsers never transmit the fragment to HTTP servers, WebSocket trackers, or reverse proxies. - **Blind Room Hash for Signaling**: The signaling server only receives an irreversible SHA-256 digest (`sha256Hex('studioswarm:zk-tracker:v1:' + roomId)`). The server never sees room names, filenames, file sizes, or decryption keys. ### 2.4 Priority Playhead Scrubbing (`src/ui/nle-timeline.ts` & `src/core/swarm-engine.ts`) - Allows editors and clients to scrub to any frame in a partially downloaded 4K video. - StudioSwarm recalculates piece priorities, placing a 6-piece rolling window ahead of the playhead into `PRIORITY` state. The swarm reprioritizes network chunk dispatching to that exact byte range so playback begins within seconds. --- ## 3. In-Browser AI Agent API (`window.StudioSwarmAgent`) When an autonomous AI agent (Claude Computer Use, Playwright, Puppeteer, web subagent) loads `/app`, the StudioSwarm engine attaches a programmatic driver to `window.StudioSwarmAgent`: ### 3.1 Method Signatures - **`createTicket(options?: { folderName?: string; pieceSizeMB?: number }): Promise`**: Creates an E2EE swarm ticket containing the room URL, key, and summary. - **`acceptTicket(ticketUrl: string, options?: { destinationMode?: 'OPFS_FALLBACK' | 'NATIVE_FS_ACCESS'; autoStart?: boolean }): Promise<{ status: string; roomId: string; destination: string }>`**: Accepts a ticket, mounts the destination storage volume, and starts direct P2P streaming. - **`fetchPiece(fileId: string, pieceIndex: number): Promise`**: Selective Ghost Inspection: downloads or reads only the requested piece (16 MB) on demand for immediate analysis. - **`prioritizePlayhead(fileId: string, ratio: number): void`**: Commands the P2P swarm to prioritize bytes near `ratio` (0.0 to 1.0). - **`exportDeliveryReceipt(): AgentDeliveryReceipt`**: Exports an immutable cryptographic JSON receipt containing per-file SHA-256 hashes and piece counts. - **`on(event: 'progress' | 'complete' | 'peer-joined' | 'peer-left' | 'error', callback: Function): () => void`**: Native event listener returning an unbind function. - **`getState(): SwarmRoomState`**: Returns current room state snapshot. - **`getTelemetry(): SwarmTelemetryMetrics`**: Returns live transfer throughput, peer counts, and RAM footprint. - **`disconnect(): void`**: Terminates transport and cleans up session. --- ## 4. Endpoints & API Specification | Endpoint | Method | Description | | :--- | :--- | :--- | | `/` | GET | Promotional Portal, ROI Calculator, and Creator Registration | | `/app` | GET | StudioSwarm PWA Workspace & `window.StudioSwarmAgent` Driver | | `/health` | GET | Zero-knowledge status check (returns `{ status: "ok", zeroKnowledge: true }`) | | `/tracker` | WebSocket | RFC 6455 Stateless Zero-Knowledge Signaling Relay | | `/api/agent-manifest.json` | GET | Machine-readable capabilities, protocols, and endpoints for AI agents | | `/api/auth/register` | POST | Register creator account with name, email, password, and creator role | | `/api/auth/login` | POST | Authenticate creator account | | `/api/billing/create-checkout-session` | POST | Initialize Stripe 7-day free trial card setup checkout session | | `/api/billing/status` | GET / POST | Check active subscription or trial status, card presence, and days remaining | | `/api/billing/confirm-trial` | POST | Confirm trial activation after Stripe Checkout redirect | | `/api/billing/webhook` | POST | Stripe webhook endpoint (listens to invoice and subscription lifecycle events) | | `/llms.txt` | GET | Concise summary for AI search and agent context | | `/llms-full.txt` | GET | Full reference documentation | --- ## 5. Competitive Comparison | Feature | StudioSwarm | Frame.io Pro | WeTransfer Pro | MASV | | :--- | :--- | :--- | :--- | :--- | | **Pricing** | $0 / Free | $15–$50/seat/mo | $144/year | $0.25/GB ($250/TB) | | **Storage Limits** | Unlimited (Local SSD) | 250 GB–1 TB cap | 200 GB max | Pay-per-GB | | **Cloud Upload Wait** | 0 minutes | 45–120 minutes | 30–90 minutes | Full upload time | | **End-to-End Encryption** | Yes (AES-GCM-256) | No (Cloud-accessible) | No | Encrypted at rest only | | **Zero Knowledge** | Yes (`#k=` isolated) | No | No | No | | **Playhead Scrubbing** | Yes (Instant) | Only after transcode | No (Full download) | No | --- ## 6. Security & Defensive Compliance - **CWE-22 Protected**: Path traversal stripped via leaf basename sanitization. - **CWE-290 Protected**: Immutable WebSocket socket-to-peer binding prevents identity spoofing. - **CWE-346 Protected**: Strict Origin header verification blocks Cross-Site WebSocket Hijacking (CSWSH). - **CWE-400 / CWE-770 Protected**: Max 32 MB chunk frames, 64 concurrent assemblies, 4-piece pre-mount buffer limit. - **Zero Third-Party Trackers**: No cookies, no Google Analytics, no external CDNs.