Compare commits

...

8 Commits

Author SHA1 Message Date
KoalaDev 3062e6c93c test: cover HTML parser regressions 2026-08-01 10:15:56 +02:00
KoalaDev ec6865a0e7 test: parse help HTML with cheerio 2026-08-01 10:04:29 +02:00
Timo 816cc38ea4 fix: align help accordions consistently 2026-07-31 10:55:06 +02:00
Timo 9ade6b67ea docs: compact help topics with accordions 2026-07-31 10:46:19 +02:00
Timo 5b75bde9bb docs: expand product help guide 2026-07-31 10:10:08 +02:00
Timo 88e777eb44 docs: move v3.0.2 chat summary to changelog 2026-07-31 09:59:41 +02:00
Timo c04c501e6d docs: record v3.0.2 chat improvements 2026-07-31 09:58:23 +02:00
GitHub Action da93c09a93 chore(release): update versions to v3.0.2 [skip ci] 2026-07-31 07:48:55 +00:00
13 changed files with 376 additions and 109 deletions
+2 -2
View File
@@ -6,7 +6,7 @@
<p align="center">
<a href="https://github.com/Shik3i/KoalaSync/actions/workflows/release.yml"><img src="https://github.com/Shik3i/KoalaSync/actions/workflows/release.yml/badge.svg" alt="Release Status"></a>
<a href="https://github.com/Shik3i/KoalaSync/releases"><img src="https://img.shields.io/badge/Release-v3.0.1-blue?logo=github" alt="GitHub release"></a>
<a href="https://github.com/Shik3i/KoalaSync/releases"><img src="https://img.shields.io/badge/Release-v3.0.2-blue?logo=github" alt="GitHub release"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License"></a>
<a href="https://addons.mozilla.org/de/firefox/addon/koalasync/"><img src="https://img.shields.io/badge/Firefox-Download-orange?logo=firefoxbrowser&logoColor=white" alt="Firefox Add-on"></a>
<a href="https://chromewebstore.google.com/detail/koalasync/obbnmkmlaaddodakcbdljknjpagklifc"><img src="https://img.shields.io/badge/Chrome-Download-blue?logo=googlechrome&logoColor=white" alt="Chrome Extension"></a>
@@ -15,7 +15,7 @@
<p align="center"><i>KoalaSync is a lightweight Browser Extension and Relay Server for synchronized video playback on almost any website with a video element—YouTube, Twitch, Netflix, Emby, Jellyfin, and beyond. Built with a focus on <b>Data Sovereignty</b> and <b>Performance</b>.</i></p>
<p align="center"><a href="docs/CHANGELOG.md"><b>New v3.0.1 Release!</b> — See what's changed</a></p>
<p align="center"><a href="docs/CHANGELOG.md"><b>New v3.0.2 Release!</b> — See what's changed</a></p>
### 🌟 Why KoalaSync?
+4
View File
@@ -6,6 +6,10 @@ All notable changes to the KoalaSync browser extension and relay server.
## [v3.0.2] — 2026-07-31
This release adds three focused chat improvements: encrypted quick-reaction emojis,
acknowledged splitting of messages up to 5000 Unicode code points, and true left/right
docking that prevents the selected page content from continuing behind the chat.
### Added
- **Extension: Quick reactions** — Adds six encrypted one-click reactions with a local choice between chat-only display and bounded falling reactions over the video.
- **Extension: Resilient chat activity** — Keeps a bounded per-room browser-session timeline for play, pause, seek, force-sync, join, and leave rows so overlay reinjection no longer loses them.
+1 -1
View File
@@ -3,7 +3,7 @@
"default_locale": "en",
"name": "__MSG_appName__",
"short_name": "KoalaSync",
"version": "3.0.1",
"version": "3.0.2",
"description": "__MSG_appDesc__",
"permissions": [
"storage",
+3 -2
View File
@@ -1,17 +1,18 @@
{
"name": "koalasync",
"version": "2.6.4",
"version": "3.0.2",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "koalasync",
"version": "2.6.4",
"version": "3.0.2",
"devDependencies": {
"@playwright/test": "^1.62.0",
"@vitest/coverage-v8": "^4.1.10",
"addons-linter": "^10.9.0",
"archiver": "^8.0.0",
"cheerio": "^1.2.0",
"esbuild": "^0.28.1",
"eslint": "^10.8.0",
"eslint-plugin-no-unsanitized": "^4.1.5",
+2 -1
View File
@@ -1,6 +1,6 @@
{
"name": "koalasync",
"version": "3.0.1",
"version": "3.0.2",
"description": "KoalaSync Build Scripts",
"private": true,
"type": "module",
@@ -22,6 +22,7 @@
"@vitest/coverage-v8": "^4.1.10",
"addons-linter": "^10.9.0",
"archiver": "^8.0.0",
"cheerio": "^1.2.0",
"esbuild": "^0.28.1",
"eslint": "^10.8.0",
"eslint-plugin-no-unsanitized": "^4.1.5",
+49
View File
@@ -3,6 +3,7 @@
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { load } from 'cheerio';
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const template = fs.readFileSync(path.join(repoRoot, 'website', 'template.html'), 'utf8');
@@ -132,6 +133,54 @@ for (const metadata of requiredHelpMetadata) {
throw new Error(`help.html is missing SEO/AEO metadata: ${metadata}`);
}
}
const helpDocument = load(helpPage);
const helpStructuredDataScripts = helpDocument('script[type="application/ld+json"]');
if (helpStructuredDataScripts.length !== 1) {
throw new Error('help.html must contain JSON-LD structured data');
}
const helpStructuredData = JSON.parse(helpStructuredDataScripts.html());
const helpFaqPage = helpStructuredData['@graph'].find(item => (
Array.isArray(item['@type']) && item['@type'].includes('FAQPage')
));
const visibleTextFromDocument = document => document('body')
.clone()
.find('script, style, noscript')
.remove()
.end()
.text()
.replace(/\s+/g, ' ');
const parserRegressionCases = [
[
'case-insensitive non-visible element filtering',
'<body><p>visible</p><SCRIPT>secret()</SCRIPT><style>hidden</style><noscript>hidden</noscript></body>',
'visible'
],
[
'single-pass HTML entity decoding',
'<body><p>A &amp;amp; B</p></body>',
'A &amp; B'
],
[
'visible text does not include attributes',
'<body><div data-faq="not visible">visible</div></body>',
'visible'
]
];
for (const [label, html, expected] of parserRegressionCases) {
const actual = visibleTextFromDocument(load(html));
if (actual !== expected) {
throw new Error(`HTML parser regression: ${label}; expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
}
}
const helpVisibleText = visibleTextFromDocument(helpDocument);
for (const question of helpFaqPage?.mainEntity || []) {
if (!helpVisibleText.includes(question.name) || !helpVisibleText.includes(question.acceptedAnswer?.text)) {
throw new Error(`help.html FAQ content must be visible and exact: ${question.name}`);
}
}
if ((helpPage.match(/class="support-card support-anchor-section support-accordion"/g) || []).length < 10) {
throw new Error('help.html must keep advanced and troubleshooting sections compact with native accordions');
}
if (!llmsText.includes('[Help Center](https://sync.koalastuff.net/help)')
|| !llmsText.includes('[Website access guide](https://sync.koalastuff.net/site-access-help)')) {
throw new Error('llms.txt must expose the Help Center and website-access guide');
+1 -1
View File
@@ -7,7 +7,7 @@
*/
export const PROTOCOL_VERSION = "1.0.0";
export const APP_VERSION = "3.0.1";
export const APP_VERSION = "3.0.2";
export const OFFICIAL_SERVER_URL = 'wss://syncserver.koalastuff.net';
export const OFFICIAL_LANDING_PAGE_URL = 'https://sync.koalastuff.net';
+14
View File
@@ -1760,6 +1760,20 @@ document.addEventListener('DOMContentLoaded', () => {
updateDynamicVersion();
localizeHomeLinks();
initLanguageSelectorValue();
const openSupportAccordion = hash => {
if (!hash || hash === '#') return;
const target = document.getElementById(decodeURIComponent(hash.slice(1)));
if (target?.matches('details.support-accordion')) {
target.open = true;
window.requestAnimationFrame(() => target.scrollIntoView({ block: 'start' }));
}
};
openSupportAccordion(window.location.hash);
window.addEventListener('hashchange', () => openSupportAccordion(window.location.hash));
document.addEventListener('click', event => {
const link = event.target.closest('a[href^="#"]');
if (link) openSupportAccordion(link.hash);
});
if (document.fonts?.ready) {
document.fonts.ready.then(adjustDropdownWidth);
}
+244 -98
View File
@@ -3,8 +3,8 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>KoalaSync Help | Setup, Chat, Privacy & Troubleshooting</title>
<meta name="description" content="Get KoalaSync working, fix invite and chat problems, understand supported devices and data handling, and verify official open-source releases.">
<title>KoalaSync Help | Rooms, Video Sync, Audio & Troubleshooting</title>
<meta name="description" content="Set up KoalaSync, create or join rooms, select a video, use sync and host controls, configure audio and privacy, and troubleshoot common problems.">
<meta name="robots" content="index, follow">
<link rel="preload" href="style.min.css" as="style">
<link rel="stylesheet" href="style.min.css">
@@ -16,7 +16,7 @@
<meta property="og:type" content="website">
<meta property="og:url" content="https://sync.koalastuff.net/help">
<meta property="og:title" content="KoalaSync Help">
<meta property="og:description" content="Setup help, invite troubleshooting, encrypted chat, supported devices, privacy, open-source releases, and reproducible bug reports.">
<meta property="og:description" content="User guides for rooms, video selection, synchronization, host controls, episodes, audio, chat, privacy, compatibility, and troubleshooting.">
<meta property="og:image" content="https://sync.koalastuff.net/assets/og-image.png">
<meta property="og:image:width" content="1280">
<meta property="og:image:height" content="640">
@@ -25,7 +25,7 @@
<meta property="og:site_name" content="KoalaSync">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="KoalaSync Help">
<meta name="twitter:description" content="Setup help, invite troubleshooting, encrypted chat, supported devices, privacy, open-source releases, and reproducible bug reports.">
<meta name="twitter:description" content="User guides for rooms, video selection, synchronization, host controls, episodes, audio, chat, privacy, compatibility, and troubleshooting.">
<meta name="twitter:image" content="https://sync.koalastuff.net/assets/og-image.png">
<meta name="twitter:image:alt" content="KoalaSync browser extension">
<meta name="theme-color" content="#10190e">
@@ -51,93 +51,133 @@
"@type": ["CollectionPage", "FAQPage"],
"@id": "https://sync.koalastuff.net/help#webpage",
"name": "KoalaSync Help",
"headline": "KoalaSync Help: Setup, Chat, Privacy and Troubleshooting",
"description": "Help for joining rooms, granting browser access, fixing encrypted room chat and playback synchronization, understanding data handling, and verifying official releases.",
"headline": "KoalaSync Help: Rooms, Video Sync, Audio and Troubleshooting",
"description": "Help for setting up KoalaSync, creating and joining rooms, selecting videos, using synchronization and host controls, configuring audio and privacy, and diagnosing problems.",
"url": "https://sync.koalastuff.net/help",
"datePublished": "2026-07-28",
"dateModified": "2026-07-28",
"dateModified": "2026-07-31",
"inLanguage": "en",
"isPartOf": {"@id": "https://sync.koalastuff.net/#website"},
"publisher": {"@id": "https://sync.koalastuff.net/#organization"},
"mainEntity": [
{
"@type": "Question",
"name": "Why does the browser show such a broad permission warning for KoalaSync?",
"name": "Install KoalaSync and prepare your browser",
"acceptedAnswer": {
"@type": "Answer",
"text": "KoalaSync works with video players across many websites. It uses access on the video tab you actively select to find and control the video element, synchronize playback, and display optional room chat. Open tab titles populate the tab selector; KoalaSync does not create a general browsing or watch history."
"text": "KoalaSync does not provide or stream the video. Everyone opens the same content locally, and KoalaSync coordinates playback controls."
}
},
{
"@type": "Question",
"name": "Why does a KoalaSync invite link not join the room?",
"name": "Play, pause, seek, and Force Sync",
"acceptedAnswer": {
"@type": "Answer",
"text": "Open the complete invite link in the same desktop browser profile where KoalaSync is installed. If the invite page was already open when the extension was installed or enabled, reload it. Confirm that the browser allows KoalaSync to run on sync.koalastuff.net, then ask the sender for a newly copied invite if the link is incomplete."
"text": "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."
}
},
{
"@type": "Question",
"name": "Why does a video tab not appear in KoalaSync?",
"name": "Choose who can control the room",
"acceptedAnswer": {
"@type": "Answer",
"text": "Reload the video page, reopen KoalaSync, and disable Hide Clutter Tabs in Settings. If the tab then appears, report the domain because it was filtered by mistake. Otherwise, verify that KoalaSync has website access."
"text": "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."
}
},
{
"@type": "Question",
"name": "Why does KoalaSync find no video on a listed tab?",
"name": "Use Auto-Sync Next Episode",
"acceptedAnswer": {
"@type": "Answer",
"text": "Select the tab containing the visible player and start playback once. Check Video Debug Info in the Status tab, reload after permission changes, and temporarily disable extensions that modify the player. Some protected or non-HTML5 players may need site-specific support."
"text": "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."
}
},
{
"@type": "Question",
"name": "Why does KoalaSync room chat not work for everyone?",
"name": "Balance quiet and loud scenes with Audio Processing",
"acceptedAnswer": {
"@type": "Answer",
"text": "Room chat requires KoalaSync 3.0.0 or newer. The room creator receives a chat encryption secret when creating a new room, and every friend must join through that room's current invite link to receive the same secret. Manual room entry and old invite links can still join playback synchronization, but do not provide chat access."
"text": "Audio Processing affects only your selected video in your browser. It is not shared or synchronized with the room."
}
},
{
"@type": "Question",
"name": "Why are connected KoalaSync participants not synchronized?",
"name": "Why does the browser show such a broad warning?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Confirm that everyone uses the same KoalaSync version and selected the correct local video tab. Reload after website-access changes, test play, pause, and seeking separately, and collect a debug report from each affected participant."
"text": "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."
}
},
{
"@type": "Question",
"name": "Does KoalaSync stream the video to other participants?",
"name": "The invite opens, but nothing happens",
"acceptedAnswer": {
"@type": "Answer",
"text": "No. KoalaSync does not stream, upload, proxy, share, or bypass access to video content. Everyone watches locally in their own browser and needs their own access to the website or streaming service. KoalaSync only synchronizes playback actions such as play, pause, and seeking."
"text": "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."
}
},
{
"@type": "Question",
"name": "Which devices and browsers support KoalaSync?",
"name": "The video tab does not appear",
"acceptedAnswer": {
"@type": "Answer",
"text": "KoalaSync is a desktop browser extension for Chrome, Firefox, Edge, and compatible Chromium-based browsers on Windows, macOS, Linux, and ChromeOS. It does not currently provide a mobile app or Safari extension. Website compatibility also depends on the site's video player."
"text": "Keep the video page open and reload it once."
}
},
{
"@type": "Question",
"name": "What data does KoalaSync send from the browser?",
"name": "The tab appears, but KoalaSync finds no usable video",
"acceptedAnswer": {
"@type": "Answer",
"text": "While you are in a room, KoalaSync sends the room, peer, and playback data needed for live synchronization. Display names and, depending on privacy settings, tab or media titles may be shared with room participants. Chat text is encrypted in the extension before transmission. KoalaSync does not create a persistent chat, browsing, synchronization, or watch history."
"text": "Select the exact tab containing the visible player, not a login, search, or media-library tab."
}
},
{
"@type": "Question",
"name": "How can official KoalaSync releases be verified?",
"name": "Chat does not work, or one person cannot see it",
"acceptedAnswer": {
"@type": "Answer",
"text": "The extension, relay server, build scripts, release workflow, and Dockerfile are public under the MIT License. Extension ZIPs on GitHub Releases and Docker images on GitHub Container Registry receive signed provenance attestations that bind their exact digest to this repository, a release tag and commit, and the public GitHub Actions workflow."
"text": "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."
}
},
{
"@type": "Question",
"name": "Everyone is connected, but playback does not sync",
"acceptedAnswer": {
"@type": "Answer",
"text": "Make sure everyone uses a currently supported KoalaSync version. Different supported versions can work together, but optional features may not be available to everyone."
}
},
{
"@type": "Question",
"name": "Does KoalaSync send the video to my friends?",
"acceptedAnswer": {
"@type": "Answer",
"text": "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."
}
},
{
"@type": "Question",
"name": "Browsers, websites, and known limitations",
"acceptedAnswer": {
"@type": "Answer",
"text": "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."
}
},
{
"@type": "Question",
"name": "What data leaves my browser?",
"acceptedAnswer": {
"@type": "Answer",
"text": "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."
}
},
{
"@type": "Question",
"name": "Why should I trust KoalaSync?",
"acceptedAnswer": {
"@type": "Answer",
"text": "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."
}
}
]
@@ -196,7 +236,7 @@
<header class="support-hero">
<span class="support-status">Help center</span>
<h1>KoalaSync Help & Troubleshooting</h1>
<p class="support-lead">Start with the problem or question you have. These guides cover invites, browser access, video detection, encrypted chat, playback synchronization, supported devices, privacy, and release verification.</p>
<p class="support-lead">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.</p>
</header>
<section class="support-topic-index" aria-labelledby="start-title">
@@ -204,53 +244,137 @@
<div class="support-topic-grid">
<article class="support-card support-topic-group">
<header class="support-topic-header">
<h3>Get connected</h3>
<p>Join a room and give KoalaSync the access it needs.</p>
<h3>Start watching together</h3>
<p>Install KoalaSync, join a room, and select your video.</p>
</header>
<div class="support-topic-links" role="navigation" aria-label="Get connected help">
<a href="#invite-problems">The invite opens, but nothing happens</a>
<a href="site-access-help">KoalaSync cannot access the video site</a>
<a href="#missing-tab">The video tab does not appear</a>
<a href="#first-setup">First setup</a>
<a href="#rooms">Create or join a room</a>
<a href="#select-video">Select the video to synchronize</a>
</div>
</article>
<article class="support-card support-topic-group">
<header class="support-topic-header">
<h3>Playback & chat</h3>
<p>Fix the selected player, room chat, or synchronization.</p>
<h3>Playback & room controls</h3>
<p>Use synchronization, host roles, and episode changes.</p>
</header>
<div class="support-topic-links" role="navigation" aria-label="Playback and chat help">
<a href="#video-detection">The tab appears, but KoalaSync finds no usable video</a>
<a href="#room-chat">Chat does not work, or one person cannot see it</a>
<a href="#sync-problems">Everyone is connected, but playback does not sync</a>
<div class="support-topic-links" role="navigation" aria-label="Playback and room control help">
<a href="#sync-controls">Synchronization and Force Sync</a>
<a href="#host-control">Host Control and Co-Hosts</a>
<a href="#episode-sync">Auto-Sync Next Episode</a>
</div>
</article>
<article class="support-card support-topic-group">
<header class="support-topic-header">
<h3>Using KoalaSync</h3>
<p>Understand what the extension does and supports.</p>
<h3>Features & settings</h3>
<p>Configure local audio, chat, titles, and relays.</p>
</header>
<div class="support-topic-links" role="navigation" aria-label="Using KoalaSync help">
<a href="#video-access">Does KoalaSync send the video to my friends?</a>
<a href="#supported-devices">Which devices and browsers are supported?</a>
<a href="#audio-processing">Audio Processing</a>
<a href="#room-chat">Room Chat</a>
<a href="#title-privacy">Title privacy</a>
<a href="#custom-relay">Custom Relay and self-hosting</a>
</div>
</article>
<article class="support-card support-topic-group">
<header class="support-topic-header">
<h3>Privacy & trust</h3>
<p>See what is shared and how official builds are verified.</p>
<h3>Compatibility & troubleshooting</h3>
<p>Fix access, detection, connection, and sync problems.</p>
</header>
<div class="support-topic-links" role="navigation" aria-label="Privacy and trust help">
<a href="#permissions">Why does the browser show such a broad warning?</a>
<a href="#data-handling">What data leaves my browser?</a>
<a href="#trust">Why should I trust KoalaSync?</a>
<div class="support-topic-links" role="navigation" aria-label="Compatibility and troubleshooting help">
<a href="#compatibility">Browsers, websites, and limitations</a>
<a href="#permissions">Privacy and browser permissions</a>
<a href="#invite-problems">Invite problems</a>
<a href="#video-detection">Video detection problems</a>
<a href="#report-issue">Debug reports and bug reports</a>
</div>
</article>
</div>
</section>
<section id="invite-problems" class="support-card support-anchor-section" aria-labelledby="invite-problems-title">
<span class="support-eyebrow">Invite links</span>
<h2 id="invite-problems-title">The invite opens, but nothing happens</h2>
<details id="first-setup" class="support-card support-anchor-section support-accordion" aria-labelledby="first-setup-title">
<summary><span class="support-eyebrow">First setup</span><h2 id="first-setup-title">Install KoalaSync and prepare your browser</h2></summary>
<ol class="support-steps">
<li>Install KoalaSync from the official Chrome, Firefox, or Edge store. Pin the KoalaSync icon to the browser toolbar if you want quicker access.</li>
<li>Each person needs KoalaSync in their own supported desktop browser and their own access to the video website.</li>
<li>Open the extension once. The short tutorial points to the <strong>Room</strong>, <strong>Sync</strong>, and <strong>Settings</strong> tabs; you can restart it later under <strong>Settings → Troubleshooting</strong>.</li>
<li>Choose a recognizable username under <strong>Settings → Profile &amp; Appearance</strong>. It is shown to the other people in the room.</li>
<li>Open the video website. If the browser asks whether KoalaSync may access it, allow access for that site and reload the page.</li>
</ol>
<p>KoalaSync does not provide or stream the video. Everyone opens the same content locally, and KoalaSync coordinates playback controls.</p>
</details>
<details id="rooms" class="support-card support-anchor-section support-accordion" aria-labelledby="rooms-title">
<summary><span class="support-eyebrow">Rooms &amp; invitations</span><h2 id="rooms-title">Create a room or join your friends</h2></summary>
<h3>Create and invite</h3>
<ol class="support-steps">
<li>Open KoalaSync and select <strong>Room</strong>.</li>
<li>Click <strong>Create New Room</strong>. By default, KoalaSync copies the new invite link to your clipboard.</li>
<li>Share the complete invite link only with the intended participants. The part after <code>#</code> contains the room credentials and the secret needed for encrypted chat.</li>
<li>After joining, use the participant list to confirm who is connected.</li>
</ol>
<h3>Join</h3>
<p>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 <strong>Manual Connect / Advanced</strong> 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.</p>
<p>Room credentials remain available locally until you leave or replace the room. Click <strong>Leave Room</strong> when you are finished.</p>
</details>
<details id="select-video" class="support-card support-anchor-section support-accordion" aria-labelledby="select-video-title">
<summary><span class="support-eyebrow">Video selection</span><h2 id="select-video-title">Choose the local video tab</h2></summary>
<ol class="support-steps">
<li>Open the video you want to watch and start it once so the player is loaded.</li>
<li>Open KoalaSync, select <strong>Sync</strong>, then choose the browser tab under <strong>Select Video</strong>.</li>
<li>Every participant selects their own local video tab. Selecting yours does not select or open a tab for anyone else.</li>
<li>Use the highlighted matching titles as a hint, not a guarantee. Confirm the episode or video yourself before synchronizing.</li>
</ol>
<p><strong>Hide Clutter Tabs</strong> removes likely non-video tabs from the list. Turn it off under <strong>Settings → Playback &amp; Sync</strong> if the correct tab is missing.</p>
</details>
<details id="sync-controls" class="support-card support-anchor-section support-accordion" aria-labelledby="sync-controls-title">
<summary><span class="support-eyebrow">Synchronization &amp; control</span><h2 id="sync-controls-title">Play, pause, seek, and Force Sync</h2></summary>
<p>When room control is open to everyone, actions on the selected player and the popup's <strong>Play</strong> and <strong>Pause</strong> buttons are sent to the room. The <strong>Last Activity Status</strong> shows the most recent room action.</p>
<ul>
<li><strong>Jump to Others:</strong> moves your selected video to the known time reported by other participants. It requires another participant with a usable playback time.</li>
<li><strong>Jump to Me:</strong> uses your selected video's current time as the target and moves the room to you.</li>
<li><strong>Sync:</strong> runs the selected Force Sync mode as a coordinated room action. Use it when normal play, pause, or seeking left someone behind.</li>
</ul>
<p>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.</p>
</details>
<details id="host-control" class="support-card support-anchor-section support-accordion" aria-labelledby="host-control-title">
<summary><span class="support-eyebrow">Host &amp; Co-Hosts</span><h2 id="host-control-title">Choose who can control the room</h2></summary>
<p>The person who created the room is the host. Under <strong>Room → Host Control</strong>, the host can enable <strong>Only I can control playback</strong>. The host can then use <strong>Give control</strong> beside individual participants to make them controllers, and <strong>Revoke</strong> to remove that role.</p>
<ul>
<li>Hosts and granted controllers can move the shared room with play, pause, seek, Force Sync, and episode-lobby actions.</li>
<li>A guest action that conflicts with Host Control may briefly affect only that guest's local player before KoalaSync restores the shared state.</li>
<li>A guest can choose <strong>Watch on my own</strong> to enter <strong>Solo</strong> mode. Host commands are then ignored locally until the guest clicks <strong>Resync</strong>.</li>
<li>If the host leaves while others remain, another participant becomes host and control returns to everyone.</li>
</ul>
</details>
<details id="episode-sync" class="support-card support-anchor-section support-accordion" aria-labelledby="episode-sync-title">
<summary><span class="support-eyebrow">Episode changes</span><h2 id="episode-sync-title">Use Auto-Sync Next Episode</h2></summary>
<p><strong>Auto-Sync Next Episode</strong> is enabled by default under <strong>Settings → Playback &amp; Sync</strong>. On supported sites, KoalaSync detects a recognizable episode change, pauses, and opens an <strong>Episode Lobby</strong> while participants load the same episode. Playback starts together when the lobby is ready.</p>
<ul>
<li>Use <strong>Skip &amp; Play anyway</strong> if you do not want to wait.</li>
<li>A timeout or participants leaving can cancel the lobby; use manual selection and Force Sync afterward.</li>
<li>The feature depends on usable episode titles. It is not available for ordinary single videos, and some services expose too little episode information.</li>
<li>Choosing <strong>Do not send</strong> for media titles prevents creation of an episode lobby. <strong>Send episode ID</strong> can preserve episode matching without sharing the full media title when an episode ID is detectable.</li>
</ul>
</details>
<details id="audio-processing" class="support-card support-anchor-section support-accordion" aria-labelledby="audio-processing-title">
<summary><span class="support-eyebrow">Local audio</span><h2 id="audio-processing-title">Balance quiet and loud scenes with Audio Processing</h2></summary>
<p>Open <strong>Settings → Playback &amp; Sync → Audio Processing</strong>. Enable Audio Processing and the compressor, then start with a preset such as <strong>Recommended</strong>, <strong>Dynamic Range</strong>, <strong>Vocal Enhancement</strong>, or <strong>Smooth</strong>. Selecting <strong>Custom</strong> exposes the compressor controls.</p>
<ul>
<li>Audio Processing affects only your selected video in your browser. It is not shared or synchronized with the room.</li>
<li>It changes audio dynamics, not the room's playback timing.</li>
<li>The Equalizer is marked <strong>Coming soon</strong> and is not currently available.</li>
<li>If a site replaces its player or audio stops behaving normally, reload the page and reselect the tab; disable Audio Processing to compare.</li>
</ul>
</details>
<details id="invite-problems" class="support-card support-anchor-section support-accordion" aria-labelledby="invite-problems-title">
<summary><span class="support-eyebrow">Invite links</span><h2 id="invite-problems-title">The invite opens, but nothing happens</h2></summary>
<ol class="support-steps">
<li>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.</li>
<li>If you installed, enabled, or updated KoalaSync after opening the invite, reload the invite page once so the extension can connect to it.</li>
@@ -265,11 +389,10 @@
<p>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.</p>
</div>
</div>
</section>
</details>
<section id="missing-tab" class="support-card support-anchor-section" aria-labelledby="missing-tab-title">
<span class="support-eyebrow">Tab list</span>
<h2 id="missing-tab-title">The video tab does not appear</h2>
<details id="missing-tab" class="support-card support-anchor-section support-accordion" aria-labelledby="missing-tab-title">
<summary><span class="support-eyebrow">Tab list</span><h2 id="missing-tab-title">The video tab does not appear</h2></summary>
<ol class="support-steps">
<li>Keep the video page open and reload it once.</li>
<li>Close and reopen the KoalaSync popup, then check <strong>Select Video</strong> again.</li>
@@ -284,11 +407,10 @@
<p>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 <code>video.example.com</code> is usually enough; do not publish a private URL containing account or session details.</p>
</div>
</div>
</section>
</details>
<section id="video-detection" class="support-card support-anchor-section" aria-labelledby="video-detection-title">
<span class="support-eyebrow">Video detection</span>
<h2 id="video-detection-title">The tab appears, but KoalaSync finds no usable video</h2>
<details id="video-detection" class="support-card support-anchor-section support-accordion" aria-labelledby="video-detection-title">
<summary><span class="support-eyebrow">Video detection</span><h2 id="video-detection-title">The tab appears, but KoalaSync finds no usable video</h2></summary>
<ul>
<li>Select the exact tab containing the visible player, not a login, search, or media-library tab.</li>
<li>Start the video once. Some websites create their video element only after playback begins.</li>
@@ -297,12 +419,12 @@
<li>Temporarily disable other extensions that modify the player, then reload and test again.</li>
<li>Protected, heavily customized, or non-HTML5 players may require site-specific support.</li>
</ul>
</section>
</details>
<section id="room-chat" class="support-card support-anchor-section" aria-labelledby="room-chat-title">
<span class="support-eyebrow">Room chat</span>
<h2 id="room-chat-title">Chat does not work, or one person cannot see it</h2>
<p>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. Older versions can still join a room and synchronize playback, but they do not support room chat.</p>
<details id="room-chat" class="support-card support-anchor-section support-accordion" aria-labelledby="room-chat-title">
<summary><span class="support-eyebrow">Room chat</span><h2 id="room-chat-title">Chat does not work, or one person cannot see it</h2></summary>
<p>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.</p>
<p>Chat is optional and appears on the selected video page. Under <strong>Settings → Room Chat</strong>, 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.</p>
<ol class="support-steps">
<li>Update KoalaSync in every browser. Open the extension and check the version in the top-right corner. Each participant needs version <strong>3.0.0 or newer</strong>.</li>
<li>After updating, the room creator should leave the old room and click <strong>Create New Room</strong>. This creates a new chat encryption secret and includes it in the new invite link.</li>
@@ -317,23 +439,47 @@
<p>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.</p>
</div>
</div>
</section>
</details>
<section id="sync-problems" class="support-card support-anchor-section" aria-labelledby="sync-problems-title">
<span class="support-eyebrow">Synchronization</span>
<h2 id="sync-problems-title">Everyone is connected, but playback does not sync</h2>
<details id="title-privacy" class="support-card support-anchor-section support-accordion" aria-labelledby="title-privacy-title">
<summary><span class="support-eyebrow">Title privacy</span><h2 id="title-privacy-title">Control which titles the room receives</h2></summary>
<p>Open <strong>Settings → Privacy</strong>. Tab titles and media titles have separate controls:</p>
<ul>
<li><strong>Send tab title:</strong> shares or withholds the title shown by the selected browser tab.</li>
<li><strong>Send full title:</strong> shares the media title detected from the player.</li>
<li><strong>Send episode ID:</strong> shares only a detected identifier such as <code>S01E04</code>. If no episode ID can be detected, no useful full title is substituted.</li>
<li><strong>Do not send:</strong> withholds the media title.</li>
</ul>
<p>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.</p>
</details>
<details id="custom-relay" class="support-card support-anchor-section support-accordion" aria-labelledby="custom-relay-title">
<summary><span class="support-eyebrow">Custom Relay &amp; self-hosting</span><h2 id="custom-relay-title">Connect to a relay you trust</h2></summary>
<p>KoalaSync uses the official relay by default. If you or someone you trust operates a compatible KoalaSync relay, open <strong>Room → Manual Connect / Advanced</strong>, choose <strong>Custom</strong>, enter its WebSocket URL, then join or create a room.</p>
<ul>
<li>Use a <code>wss://</code> URL for a relay on the public internet. Plain <code>ws://</code> is intended for local testing on <code>localhost</code>.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p><a class="support-link" href="./#self-hosting">See the self-hosting overview</a>. Deployment instructions are intended for the person operating the server; ordinary participants only need the supplied relay URL.</p>
</details>
<details id="sync-problems" class="support-card support-anchor-section support-accordion" aria-labelledby="sync-problems-title">
<summary><span class="support-eyebrow">Synchronization</span><h2 id="sync-problems-title">Everyone is connected, but playback does not sync</h2></summary>
<ol class="support-steps">
<li>Update KoalaSync in every browser and confirm everyone uses the same extension version.</li>
<li>Make sure everyone uses a currently supported KoalaSync version. Different supported versions can work together, but optional features may not be available to everyone.</li>
<li>Make sure each participant selected the correct local video tab.</li>
<li>Reload the video page after changing website access, then select the tab again.</li>
<li>Test play, pause, and seeking separately and note which action fails.</li>
<li>If the <strong>Status</strong> tab says <strong>Disconnected</strong> or <strong>Failed</strong>, click <strong>Retry</strong>. For a custom relay, confirm its URL and availability with the operator.</li>
<li>If KoalaSync reports <strong>Duplicate Identity</strong>, open <strong>Settings → Troubleshooting</strong> and click <strong>Regenerate Peer ID</strong>.</li>
<li>Before anyone leaves the room, collect a debug report from every affected participant.</li>
</ol>
</section>
</details>
<section id="video-access" class="support-card support-anchor-section" aria-labelledby="video-access-title">
<span class="support-eyebrow">Video access</span>
<h2 id="video-access-title">Does KoalaSync send the video to my friends?</h2>
<details id="video-access" class="support-card support-anchor-section support-accordion" aria-labelledby="video-access-title">
<summary><span class="support-eyebrow">Video access</span><h2 id="video-access-title">Does KoalaSync send the video to my friends?</h2></summary>
<p>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.</p>
<ul>
<li>Everyone watches the video locally in their own browser on the original website.</li>
@@ -341,31 +487,32 @@
<li>KoalaSync does not bypass subscriptions, logins, DRM, regional restrictions, or platform rules.</li>
<li>Subtitles, audio tracks, fullscreen, and video quality remain local choices when the video player supports them.</li>
</ul>
</section>
</details>
<section id="supported-devices" class="support-card support-anchor-section" aria-labelledby="supported-devices-title">
<span class="support-eyebrow">Compatibility</span>
<h2 id="supported-devices-title">Which devices and browsers are supported?</h2>
<details id="compatibility" class="support-card support-anchor-section support-accordion" aria-labelledby="supported-devices-title">
<summary><span class="support-eyebrow">Compatibility</span><h2 id="supported-devices-title">Browsers, websites, and known limitations</h2></summary>
<p>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.</p>
<ul>
<li>There is currently no KoalaSync mobile app for phones or tablets.</li>
<li>There is currently no Safari extension.</li>
<li>Website compatibility depends on the browser and the site's video player. Websites can change their players, DRM behavior, or browser restrictions at any time.</li>
<li>Protected, customized, or non-HTML5 players may need site-specific support even in a supported browser.</li>
<li>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.</li>
<li>The project's compatibility matrix currently lists playback sync as working for YouTube, Twitch, Netflix, Emby, Jellyfin, Disney+, Prime Video, and Vix. These project records are not a compatibility guarantee and do not currently include test dates or extension versions.</li>
<li>Title and episode support varies: Netflix exposes no usable media title in the recorded tests; Disney+ exposes only a partial title; automatic episode sync is recorded for Emby, Jellyfin, and Vix.</li>
<li>Plex, Max, Crunchyroll, Vimeo, Dailymotion, and ARD/ZDF are currently listed as not tested, not as supported or unsupported.</li>
<li>Website compatibility can change when a service changes its player, DRM behavior, page structure, or browser restrictions.</li>
</ul>
</section>
<p><a class="support-link" href="https://github.com/Shik3i/KoalaSync/blob/main/docs/TESTED_SERVICES.md" target="_blank" rel="noopener">View the current tested-services matrix</a></p>
</details>
<section id="permissions" class="support-card support-anchor-section" aria-labelledby="permissions-title">
<span class="support-eyebrow">Privacy & permissions</span>
<h2 id="permissions-title">Why does the browser show such a broad warning?</h2>
<details id="permissions" class="support-card support-anchor-section support-accordion" aria-labelledby="permissions-title">
<summary><span class="support-eyebrow">Privacy &amp; permissions</span><h2 id="permissions-title">Why does the browser show such a broad warning?</h2></summary>
<p>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.</p>
<p>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.</p>
<p><a class="support-link" href="privacy#extension-permissions">Read the complete permission and data-handling explanation</a></p>
</section>
</details>
<section id="data-handling" class="support-card support-anchor-section" aria-labelledby="data-handling-title">
<span class="support-eyebrow">Privacy</span>
<h2 id="data-handling-title">What data leaves my browser?</h2>
<details id="data-handling" class="support-card support-anchor-section support-accordion" aria-labelledby="data-handling-title">
<summary><span class="support-eyebrow">Privacy</span><h2 id="data-handling-title">What data leaves my browser?</h2></summary>
<p>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.</p>
<ul>
<li><strong>Room and presence:</strong> room ID, peer ID, display name, connection state, and the information needed to join the room.</li>
@@ -377,11 +524,10 @@
</ul>
<p>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.</p>
<p><a class="support-link" href="privacy">Read the complete privacy policy</a></p>
</section>
</details>
<section id="trust" class="support-card support-anchor-section" aria-labelledby="trust-title">
<span class="support-eyebrow">Trust & verification</span>
<h2 id="trust-title">Why should I trust KoalaSync?</h2>
<details id="trust" class="support-card support-anchor-section support-accordion" aria-labelledby="trust-title">
<summary><span class="support-eyebrow">Trust &amp; verification</span><h2 id="trust-title">Why should I trust KoalaSync?</h2></summary>
<p>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.</p>
<p>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.</p>
<p>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.</p>
@@ -407,13 +553,13 @@
<p>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.</p>
</div>
</div>
</section>
</details>
<section id="report-issue" class="support-card support-anchor-section" aria-labelledby="report-issue-title">
<span class="support-eyebrow">Still not working?</span>
<h2 id="report-issue-title">Create a useful GitHub issue</h2>
<details id="report-issue" class="support-card support-anchor-section support-accordion" aria-labelledby="report-issue-title">
<summary><span class="support-eyebrow">Still not working?</span><h2 id="report-issue-title">Create a useful GitHub issue</h2></summary>
<ol class="support-steps">
<li>Open KoalaSync, switch to <strong>Status</strong>, and click <strong>Copy Logs</strong> while the problem is still visible.</li>
<li>Open KoalaSync and switch to <strong>Status</strong> while the problem is still visible. Check <strong>Connection Status</strong>, <strong>Video Debug Info</strong>, <strong>Full Action History</strong>, and the last 50 connection logs.</li>
<li>Click <strong>Copy Logs</strong>. The copied debug report combines the relevant status, room, participant, video, action, and log details for troubleshooting.</li>
<li>Open the KoalaSync GitHub bug-report form and sign in to GitHub if requested.</li>
<li>Describe the exact steps that reproduce the problem, what you expected, and what happened instead.</li>
<li>Add your browser, operating system, KoalaSync version, and the affected website or domain.</li>
@@ -430,7 +576,7 @@
<a class="btn btn-primary" href="https://github.com/Shik3i/KoalaSync/issues/new?template=bug_report.md" target="_blank" rel="noopener">Create a bug report</a>
<a class="btn btn-secondary" href="https://github.com/Shik3i/KoalaSync/issues" target="_blank" rel="noopener">Search existing issues</a>
</div>
</section>
</details>
<div class="support-actions">
<a class="btn btn-secondary" href="./">Back to KoalaSync</a>
+1 -1
View File
@@ -87,7 +87,7 @@ Compatibility depends on each website's player implementation and can change whe
## Technical information
- Current website release: 3.0.1
- Current website release: 3.0.2
- License: MIT
- Extension runtime: dependency-free browser extension code
- Relay: Node.js with Socket.IO-compatible WebSocket messaging
+52
View File
@@ -238,6 +238,58 @@
scroll-margin-top: 7rem;
}
.support-accordion > summary {
display: grid;
grid-template-columns: minmax(0, 1fr) auto;
gap: 0.65rem 1rem;
align-items: center;
list-style: none;
cursor: pointer;
}
.support-accordion > summary::-webkit-details-marker {
display: none;
}
.support-accordion > summary::after {
grid-column: 2;
grid-row: 1 / span 2;
content: "";
width: 2rem;
height: 2rem;
border: 1px solid color-mix(in oklch, var(--accent) 35%, var(--card-border));
border-radius: 999px;
background:
linear-gradient(currentColor, currentColor) center / 10px 1px no-repeat,
linear-gradient(currentColor, currentColor) center / 1px 10px no-repeat;
color: var(--accent);
}
.support-accordion[open] > summary::after {
background:
linear-gradient(currentColor, currentColor) center / 10px 1px no-repeat;
}
.support-accordion > summary .support-eyebrow {
grid-column: 1;
width: fit-content;
}
.support-accordion > summary h2 {
grid-column: 1;
margin: 0;
}
.support-accordion > summary:focus-visible {
outline: 3px solid color-mix(in oklch, var(--accent) 50%, transparent);
outline-offset: 6px;
border-radius: 12px;
}
.support-accordion[open] > summary {
margin-bottom: 1rem;
}
.support-anchor-section code {
overflow-wrap: anywhere;
color: var(--text);
+1 -1
View File
@@ -116,7 +116,7 @@
"priceCurrency": "EUR"
},
"description": "{{SCHEMA_APP_DESC}}",
"softwareVersion": "3.0.1",
"softwareVersion": "3.0.2",
"license": "https://opensource.org/licenses/MIT",
"sameAs": "https://github.com/Shik3i/KoalaSync",
"image": "https://sync.koalastuff.net/assets/NewLogoIcon.webp",
+2 -2
View File
@@ -1,4 +1,4 @@
{
"version": "3.0.1",
"date": "2026-07-26T03:56:23Z"
"version": "3.0.2",
"date": "2026-07-31T07:48:55Z"
}