Skip to help topics
Help center

# KoalaSync Help & Troubleshooting

Follow the setup guides for your first watch party, or jump directly to help with rooms, video selection, synchronization, host controls, episodes, audio, chat, compatibility, privacy, self-hosting, and troubleshooting.

## Choose a help topic

### Start watching together

Install KoalaSync, join a room, and select your video.

### Playback & room controls

Use synchronization, host roles, and episode changes.

### Features & settings

Configure local audio, chat, titles, and relays.

### Compatibility & troubleshooting

Fix access, detection, connection, and sync problems.

First setup

## Install KoalaSync and prepare your browser

1. Install KoalaSync from the official Chrome, Firefox, or Edge store. Pin the KoalaSync icon to the browser toolbar if you want quicker access.
2. Each person needs KoalaSync in their own supported desktop browser and their own access to the video website.
3. Open the extension once. The short tutorial points to the Room, Sync, and Settings tabs; you can restart it later under Settings → Troubleshooting.
4. Choose a recognizable username under Settings → Profile & Appearance. It is shown to the other people in the room.
5. Open the video website. If the browser asks whether KoalaSync may access it, allow access for that site and reload the page.

KoalaSync does not provide or stream the video. Everyone opens the same content locally, and KoalaSync coordinates playback controls.

Rooms & invitations

## Create a room or join your friends

### Create and invite

1. Open KoalaSync and select Room.
2. Click Create New Room. By default, KoalaSync copies the new invite link to your clipboard.
3. Share the complete invite link only with the intended participants. The part after `#` contains the room credentials and the secret needed for encrypted chat.
4. After joining, use the participant list to confirm who is connected.

### Join

Open the invite in the same desktop browser profile where KoalaSync is installed. The join page passes the room settings to the extension. You can also use Manual Connect / Advanced to enter a room ID and optional password, or select a public room, but manual and legacy joins do not provide the current chat secret.

Room credentials remain available locally until you leave or replace the room. Click Leave Room when you are finished.

Video selection

## Choose the local video tab

1. Open the video you want to watch and start it once so the player is loaded.
2. Open KoalaSync, select Sync, then choose the browser tab under Select Video.
3. Every participant selects their own local video tab. Selecting yours does not select or open a tab for anyone else.
4. Use the highlighted matching titles as a hint, not a guarantee. Confirm the episode or video yourself before synchronizing.

Hide Clutter Tabs removes likely non-video tabs from the list. Turn it off under Settings → Playback & Sync if the correct tab is missing.

Synchronization & control

## Play, pause, seek, and Force Sync

When room control is open to everyone, actions on the selected player and the popup's Play and Pause buttons are sent to the room. The Last Activity Status shows the most recent room action.

- Jump to Others: moves your selected video to the known time reported by other participants. It requires another participant with a usable playback time.
- Jump to Me: uses your selected video's current time as the target and moves the room to you.
- Sync: runs the selected Force Sync mode as a coordinated room action. Use it when normal play, pause, or seeking left someone behind.

Force Sync cannot fix different videos, missing website access, an unloaded player, or a site that blocks the required playback action. Check that everyone selected the intended content first.

Host & Co-Hosts

## Choose who can control the room

The person who created the room is the host. Under Room → Host Control, the host can enable Only I can control playback. The host can then use Give control beside individual participants to make them controllers, and Revoke to remove that role.

- Hosts and granted controllers can move the shared room with play, pause, seek, Force Sync, and episode-lobby actions.
- A guest action that conflicts with Host Control may briefly affect only that guest's local player before KoalaSync restores the shared state.
- A guest can choose Watch on my own to enter Solo mode. Host commands are then ignored locally until the guest clicks Resync.
- If the host leaves while others remain, another participant becomes host and control returns to everyone.

Episode changes

## Use Auto-Sync Next Episode

Auto-Sync Next Episode is enabled by default under Settings → Playback & Sync. On supported sites, KoalaSync detects a recognizable episode change, pauses, and opens an Episode Lobby while participants load the same episode. Playback starts together when the lobby is ready.

- Use Skip & Play anyway if you do not want to wait.
- A timeout or participants leaving can cancel the lobby; use manual selection and Force Sync afterward.
- The feature depends on usable episode titles. It is not available for ordinary single videos, and some services expose too little episode information.
- Choosing Do not send for media titles prevents creation of an episode lobby. Send episode ID can preserve episode matching without sharing the full media title when an episode ID is detectable.

Local audio

## Balance quiet and loud scenes with Audio Processing

Open Settings → Playback & Sync → Audio Processing. Enable Audio Processing and the compressor, then start with a preset such as Recommended, Dynamic Range, Vocal Enhancement, or Smooth. Selecting Custom exposes the compressor controls.

- Audio Processing affects only your selected video in your browser. It is not shared or synchronized with the room.
- It changes audio dynamics, not the room's playback timing.
- The Equalizer is marked Coming soon and is not currently available.
- If a site replaces its player or audio stops behaving normally, reload the page and reselect the tab; disable Audio Processing to compare.

Invite links

## The invite opens, but nothing happens

1. Open the invite in the same desktop browser profile where KoalaSync is installed. Extensions installed in another browser or profile cannot receive the join request.
2. If you installed, enabled, or updated KoalaSync after opening the invite, reload the invite page once so the extension can connect to it.
3. Confirm that KoalaSync is allowed to run on `sync.koalastuff.net`. If the browser blocks access, follow the site-access guide, then reload the invite.
4. Ask the sender to open KoalaSync and copy the invite link again. Use the complete link without removing anything after `#`; that part contains the room credentials and current chat secret.
5. Wait for the join page to report success. Joining the room does not select a video automatically, so open KoalaSync afterward and choose your local video tab under Sync.

i
The extension must be detected on the invite page.

If the page still offers an install button even though KoalaSync is installed, the usual causes are a different browser profile, blocked website access, or a page that was opened before the extension became available.

Tab list

## The video tab does not appear

1. Keep the video page open and reload it once.
2. Close and reopen the KoalaSync popup, then check Select Video again.
3. Open KoalaSync Settings and turn off Hide Clutter Tabs.
4. Return to the tab selector. If the tab now appears, the site was filtered as clutter by mistake.
5. If the tab is still missing, verify website access using the site-access guide.

i
Tell us which domain was classified incorrectly.

For a false clutter match, report the domain, whether the tab appears with the filter disabled, and whether the page contains a visible HTML5 video. A domain such as `video.example.com` is usually enough; do not publish a private URL containing account or session details.

Video detection

## The tab appears, but KoalaSync finds no usable video

- Select the exact tab containing the visible player, not a login, search, or media-library tab.
- Start the video once. Some websites create their video element only after playback begins.
- Open the KoalaSync Status tab and inspect Video Debug Info.
- If the report says NO VIDEO ELEMENT, note the video count and whether Shadow DOM was detected.
- Temporarily disable other extensions that modify the player, then reload and test again.
- Protected, heavily customized, or non-HTML5 players may require site-specific support.

Room chat

## Chat does not work, or one person cannot see it

Room chat was introduced in KoalaSync 3.0.0. Every participant who wants to send or read chat messages needs version 3.0.0 or newer. Supported pre-3.0 versions may still synchronize playback, but they do not support room chat.

Chat is optional and appears on the selected video page. Under Settings → Room Chat, you can start it as a floating bubble or open overlay, dock it left or right, detach it, choose its size, control chat notifications, and keep quick reactions in chat or also show them over the video.

1. Update KoalaSync in every browser. Open the extension and check the version in the top-right corner. Each participant needs version 3.0.0 or newer.
2. After updating, the room creator should leave the old room and click Create New Room. This creates a new chat encryption secret and includes it in the new invite link.
3. Send that newly copied invite link to your friends. Each friend must leave the old room and join through the link so their extension receives the same chat encryption secret.
4. Do not join by typing only the room ID and password, and do not reuse an old invite link beginning with `#join:`. Both can connect playback synchronization, but neither contains the chat secret.
5. Each participant must select their local video tab, then open Settings → Room Chat and turn on Enable Room Chat. The chat appears on the selected video page, not inside the extension popup.

i
Chat is live only.

There is no server-side message history. Someone who joins later sees only messages sent after they joined. Keep the invite link private: it contains the chat secret used to decrypt messages in that room.

Title privacy

## Control which titles the room receives

Open Settings → Privacy. Tab titles and media titles have separate controls:

- Send tab title: shares or withholds the title shown by the selected browser tab.
- Send full title: shares the media title detected from the player.
- Send episode ID: shares only a detected identifier such as `S01E04`. If no episode ID can be detected, no useful full title is substituted.
- Do not send: withholds the media title.

Reducing title sharing can make automatic tab matching and episode coordination less informative. Disabling media-title sharing also prevents Auto-Sync Next Episode from creating a lobby.

Custom Relay & self-hosting

## Connect to a relay you trust

KoalaSync uses the official relay by default. If you or someone you trust operates a compatible KoalaSync relay, open Room → Manual Connect / Advanced, choose Custom, enter its WebSocket URL, then join or create a room.

- Use a `wss://` URL for a relay on the public internet. Plain `ws://` is intended for local testing on `localhost`.
- All participants in a room must connect to the same relay. An invite created on a custom relay includes that relay address for current KoalaSync clients.
- The operator of a custom relay controls its hosting, logging, retention, updates, and availability. The official relay's privacy policy does not describe third-party instances.
- If the custom URL is rejected or the connection fails, confirm the complete WebSocket URL with its operator. A normal website URL is not always the relay URL.

See the self-hosting overview. Deployment instructions are intended for the person operating the server; ordinary participants only need the supplied relay URL.

Synchronization

## Everyone is connected, but playback does not sync

1. Make sure everyone uses a currently supported KoalaSync version. Different supported versions can work together, but optional features may not be available to everyone.
2. Make sure each participant selected the correct local video tab.
3. Reload the video page after changing website access, then select the tab again.
4. Test play, pause, and seeking separately and note which action fails.
5. If the Status tab says Disconnected or Failed, click Retry. For a custom relay, confirm its URL and availability with the operator.
6. If KoalaSync reports Duplicate Identity, open Settings → Troubleshooting and click Regenerate Peer ID.
7. Before anyone leaves the room, collect a debug report from every affected participant.

Video access

## Does KoalaSync send the video to my friends?

No. KoalaSync does not stream, upload, proxy, download, or redistribute video content. It only sends the live room and playback events needed to keep actions such as play, pause, and seeking synchronized.

- Everyone watches the video locally in their own browser on the original website.
- Each participant needs their own valid access to the website or streaming service.
- KoalaSync does not bypass subscriptions, logins, DRM, regional restrictions, or platform rules.
- Subtitles, audio tracks, fullscreen, and video quality remain local choices when the video player supports them.

Compatibility

## Browsers, websites, and known limitations

KoalaSync is currently a desktop browser extension. It supports Google Chrome, Mozilla Firefox, Microsoft Edge, Opera, Brave, Vivaldi, and other compatible Chromium-based desktop browsers on Windows, macOS, Linux, and ChromeOS.

- There is currently no KoalaSync mobile app for phones or tablets.
- There is currently no Safari extension.
- KoalaSync targets visible HTML5 video players. Protected, customized, cross-origin, or non-HTML5 players may expose only part of the information or controls KoalaSync needs.
- The project's compatibility matrix currently lists playback sync as working for YouTube, Twitch, Netflix, Emby, Jellyfin, Disney+, Prime Video, Vix, JkAnime, Google Drive, and YummyAnime. Newer records include their test date and extension version; older entries may not.
- Google Drive and YummyAnime were manually verified with v3.1.2. Both currently place the real video inside embedded player frames, so the browser may ask for access to that external player origin.
- Title and episode support varies: Netflix exposes no usable media title in the recorded tests; Disney+ and YummyAnime expose only partial titles; automatic episode sync is recorded for Emby, Jellyfin, and Vix.
- Plex, Max, Crunchyroll, Vimeo, Dailymotion, and ARD/ZDF are currently listed as not tested, not as supported or unsupported.
- Website compatibility can change when a service changes its player, DRM behavior, page structure, or browser restrictions.

View the current tested-services matrix

Privacy & permissions

## Why does the browser show such a broad warning?

Browsers may say that KoalaSync can “read and change all your data on all websites.” The wording is broad because KoalaSync is designed to work with video players across many different websites instead of a short fixed list.

KoalaSync injects its synchronization script into the video tab you actively select. On that tab it needs to find and control the video element, synchronize play, pause, and seeking, and display the optional room chat overlay. Open tab titles are read to populate the tab selector. KoalaSync does not create a general browsing or watch history.

Read the complete permission and data-handling explanation

Privacy

## What data leaves my browser?

KoalaSync only connects to a relay while you are actively in a room. During that session, the relay temporarily processes the data required to connect participants and synchronize playback.

- Room and presence: room ID, peer ID, display name, connection state, and the information needed to join the room.
- Playback synchronization: actions and state such as play, pause, seeking, and the current playback position.
- Titles: tab or media titles may be shared with room participants depending on your title privacy settings. They can be limited or disabled.
- Room chat: message text is encrypted in the extension before transmission. The relay receives ciphertext and delivery metadata, but not the chat secret or readable message text.
- Stored locally: preferences, current room credentials, and the chat secret are stored in the browser. The chat secret is not sent to the relay. Decrypted chat entries remain only in the current page overlay and are not written to browser storage.
- Operational logs: the relay may log technical connection and security information such as IP addresses, protocol versions, socket or peer identifiers, and shortened room identifiers. Retention depends on the server infrastructure and configuration.

KoalaSync does not create a persistent browsing, room, synchronization, chat, or watch history. Browser or operating-system notifications may retain notification text according to their own settings.

Read the complete privacy policy

Trust & verification

## Why should I trust KoalaSync?

Trust should not depend on promises alone. The KoalaSync browser extension, relay server, build scripts, release workflow, and Dockerfile used for official GitHub releases are public under the MIT License.

Official extension ZIPs on GitHub Releases and Docker images on GitHub Container Registry are built by the public GitHub Actions release workflow. Signed SLSA provenance attestations connect each artifact's exact digest to this repository, its release tag and commit, and the workflow that built it.

You can install KoalaSync from an official browser store, download the Chrome or Firefox ZIP from GitHub Releases, build the extension yourself, or run your own relay server. Manual ZIP installation uses your browser's developer or manual extension installation process.

View source code Download releases View release workflow Self-host the relay
Advanced: verify signed build provenance

Install the GitHub CLI, download the release ZIP, and run:

    gh attestation verify koalasync-chrome.zip \
      --repo Shik3i/KoalaSync

To verify the current Docker image:

    gh attestation verify oci://ghcr.io/shik3i/koalasync:latest \
      --repo Shik3i/KoalaSync

!
What an attestation proves, and what it does not.

An attestation proves the origin and build workflow of the GitHub release ZIP or GHCR image with that exact digest. It does not guarantee that software has no bugs or vulnerabilities. It also does not by itself prove that a package downloaded from a browser store is byte-for-byte identical to a GitHub release ZIP.

Still not working?

## Create a useful GitHub issue

1. Open KoalaSync and switch to Status while the problem is still visible. Check Connection Status, Video Debug Info, Full Action History, and the last 50 connection logs.
2. Click Copy Logs. The copied debug report combines the relevant status, room, participant, video, action, and log details for troubleshooting.
3. Open the KoalaSync GitHub bug-report form and sign in to GitHub if requested.
4. Describe the exact steps that reproduce the problem, what you expected, and what happened instead.
5. Add your browser, operating system, KoalaSync version, and the affected website or domain.
6. Paste the debug report, add a screenshot if useful, and review everything before publishing.

!
GitHub issues are public.

The copied report can include page titles and URLs, peer and room identifiers, participant names, and a custom server URL. Remove anything private. Never publish an invite link, room password, chat secret, account token, or a URL containing private session parameters.

Create a bug report Search existing issues
Back to KoalaSync Privacy policy