# Watch together — Full AI Documentation **App Name:** Watch together **Also known as:** Cinema Stream, Watch Together App **URL:** https://together.knot-sys.com **Type:** Free, web-based, real-time collaborative watch party platform **Price:** Free (no subscription, no credit card required) **Languages supported:** English, Arabic (UI is in English; content in Arabic is supported) --- ## Overview Watch together is a browser-based application that lets groups of people — anywhere in the world — watch videos and presentations at exactly the same time with perfect synchronization. There is no software to install; it runs entirely in a web browser. A user creates a "room", shares a link with friends, and everyone in the room experiences the same video playback together. Play, pause, and seek operations made by the host (or any permitted user) are instantly reflected on everyone else's screen. --- ## Detailed Feature Breakdown ### 1. Video Playback Sources #### YouTube (Full Integration) - Paste any YouTube video URL and it plays in a synchronized player powered by the YouTube IFrame API. - An in-app YouTube browser panel lets users search YouTube directly without leaving the app. - YouTube playlists are supported: paste a playlist URL and all videos are added to the room queue. - Hosts can connect their Google account to browse their YouTube subscriptions and watch history in-app. #### Direct Video Links - Paste a direct link ending in `.mp4`, `.webm`, `.mkv`, `.avi`, `.mov`, `.flv`, or `.wmv`. - An optional CORS proxy handles cross-origin video sources that would otherwise be blocked by the browser. #### HLS & DASH Streaming - Paste any `.m3u8` URL (HTTP Live Stream) or MPEG-DASH manifest. - Ideal for live events, IPTV streams, or VOD content from CDNs. - Live stream mode disables the seek bar automatically when the stream has no duration. #### Local File Playback (No Upload Required) - The host selects a local video file from their device. - Other participants are prompted to open the **same file** from their own device. - The server does NOT receive the file — only timing signals (play/pause/seek) are transmitted. - This allows watching private or large video files without any bandwidth cost. #### Chunked File Upload & Stream - Drag and drop a video file to upload it to the server. - Uploading happens in 5 MB chunks in the background. - The host can start watching immediately (via local blob URL) while the upload continues. - Once uploaded, all participants receive the server URL and can stream the video. #### Web Page Video Scraper - Paste any webpage URL (e.g. a news article, a blog post with an embedded player). - The server scrapes the page, extracts embedded video sources, and presents quality options. - Supports multiple quality variants when the source offers them. #### IMDb Streaming - Paste an IMDb title URL (e.g. `https://www.imdb.com/title/tt1234567/`) or just the ID (e.g. `tt1234567`). - The app builds a streaming embed automatically. - For TV series: season and episode selection is available. #### Screen Sharing (WebRTC) - The host can broadcast their entire screen or a specific application window to all room participants. - Powered by the browser's native WebRTC `getDisplayMedia` API — no plugins needed. #### Camera Sharing (WebRTC) - Any room participant can share their webcam feed with the room. - Useful for reaction-cam style co-watching sessions. --- ### 2. Synchronized Playback Engine - Every play, pause, seek, and volume event is broadcast via **Socket.io** to all participants within milliseconds. - A heartbeat-based drift correction system periodically checks the playback position of all clients and re-syncs anyone who has drifted more than a configurable threshold (default: 2 seconds). - Only the designated "controller" role emits sync events, preventing event collision when multiple users have control permissions. - Live stream sources (no total duration) use a special mode that disables seek and drift correction. --- ### 3. PowerPoint Presentation Sync - Upload a `.pptx` file to the room. - The server reads the slide count from the PPTX ZIP archive. - The host navigates slides; all participants' displays advance in real time. - Each client renders slides client-side using **JSZip** + **DOMParser** to parse PPTX XML — no LibreOffice or server-side image conversion is required. - Slide thumbnails, text shapes, background colors, and embedded images render directly in the browser. --- ### 4. Room System & Access Control #### Room Creation - Any authenticated user can create a room. - Rooms can be **public** (visible in Discover) or **private** (link-only). - Optional password protection for private rooms. #### Roles | Role | Permissions | |---|---| | **Host** | Full control: create room, kick users, transfer control, all playback | | **Controller** | Can emit play/pause/seek events; set by host | | **Guest** | Watch-only by default; can be granted control or suggest-video permission | #### Room Queue - A drag-to-reorder video queue is available in every room. - Any permitted user can add videos; the host approves or removes items. - "Skip to next" and "Remove from queue" controls are accessible from the queue panel. #### Room Discovery - A public "Discover" page lists all currently active public rooms. - Users can browse rooms and join any public room without an invitation. --- ### 5. Communication & Interaction | Feature | Description | |---|---| | **Real-time Chat** | Text messages broadcast to all participants; messages are persisted for the room session | | **Emoji Reactions** | Click emoji to send animated floating reactions visible to all viewers | | **Drawing Canvas** | An annotation overlay that lets the host (or permitted users) draw on top of the video | | **Live Polls** | Host creates a poll question with options; participants vote; results update in real time | --- ### 6. Remote Control via QR Code - Every room displays a QR code. - Scanning it on a mobile phone opens a lightweight remote-control page (no separate login — authenticated via the same JWT token). - Remote supports: **Play / Pause**, **Seek ±10s**, **Volume Up / Down**, **Previous / Next Slide**, **Next Video in Queue**. --- ### 7. Shared Browser - The host can open a "shared browser" panel inside the room. - All participants see the same web page URL and scroll position in real time. - Useful for browsing content together, showing a product demo, or navigating a website collaboratively. --- ### 8. User Account & Social Features - **Authentication:** Google OAuth or email/password via Firebase Auth. - **Google Integration:** Connect Google account to access YouTube subscriptions and watch history in-app. - **Friends System:** Send/accept friend requests; see online/offline status; get notified when a friend creates a room. - **User Profiles:** Display name, bio, avatar, and activity history. - **Notifications:** In-app bell for friend requests, room invites, and mentions. - **Privacy Settings:** Control who can send you friend requests and room invites. --- ### 9. Administration & Moderation - **Report System:** Any user can report a room, another user, or a specific chat message. - **Admin Dashboard:** Moderators review reports, see reporter and reported content, and take action (warn, kick, ban). - **Host Controls:** Kick any participant from the room; revoke controller status. --- ## Technical Architecture | Layer | Technology | |---|---| | Frontend | React 18, TypeScript, Vite 5, Tailwind CSS 4 | | UI Components | Radix UI, Shadcn/ui, Lucide Icons | | Animations | Framer Motion | | Backend | Node.js 20, Express 5, Socket.io 4 | | Database | PostgreSQL (raw SQL, custom migrations) | | Auth | Firebase Auth (Google OAuth + email/password) | | JWT | jsonwebtoken (server-issued tokens for Socket.io auth) | | Real-time | Socket.io WebSockets with JWT handshake middleware | | Video Engine | YouTube IFrame API, HLS.js, native HTML5 `