Contributing

Pull requests are paused for now. 🙏 StreamXR is made by one person, who's focusing on bug fixes and the roadmap, so pull requests aren't being accepted at the moment and will be closed. Issues are very welcome: bug reports, headset reports, feature requests and translations (sent as an issue: see "Translating"). The rules below are for when pull requests open again.

Thanks for wanting to help. This project is built to stay small, readable and easy to extend, so contributions are welcome when they keep it that way. Please read this whole page before opening a pull request: pull requests that skip it are closed without review.

The short version

Open an issue first and wait for a reply before writing code. Describe what you want to change and why. This saves you from building something that won't be merged.
One change per pull request. A bug fix, a feature, or a headset's support; not all three.
Test it on real hardware in a real VR session, and say which headset, browser and VR runtime you used.
Follow the code rules below. Read the surrounding code and write like it.
You must understand every line you submit. AI tools are fine to use, but you are the author: be ready to explain any line in review. Code that looks generated and unexamined (unused code, invented APIs, comments that don't match the code, changes unrelated to the issue) is closed.

Ways to help without writing code

These are often more useful than code. Every issue goes through a form (New issue on GitHub), so it arrives with what's needed to act on it:

Headset / controller compatibility. If the extension doesn't work right on your hardware, paste the Copy details output (the form says how). That's usually enough for the fix to be written here.
YouTube changed something. YouTube changes its pages often. If something that used to work stops (Up Next is empty, a panel shows nothing), a report with the video or channel link is very valuable.
Video looks wrong in VR. A video that shows stretched, doubled, as squares or the wrong way round: the video's title, its channel and Copy details help fix its format detection.
Bug report, with steps to reproduce, the video's title and channel, and the Copy details output.
New feature request, Support for another site (check the DRM note in the form first), Documentation problem, and Question or setup help.
Security problems go privately, never in an issue: see SECURITY.md.
Translations. StreamXR's own words (buttons, panel names, messages) come from string tables, so adding your language needs no code: see "Translating" below.

Translating

Everything StreamXR writes itself is in three English tables. What the site writes (video titles, "1.2M views", comments) is not: it already arrives in your site language.

src/core/shared/strings-en.js: the core (controls panel, keyboard, help, the Laser / Keyboard / Language settings tabs).
src/streamxr/shared/strings-en.js: StreamXR (video formats, the "Watch in VR" popup, starting VR, the 2D Cinema settings tab).
src/sites/youtube/page/provider/strings-en.js: YouTube's panels (keys start with yt.).

Spanish (strings-es.js next to each) is a finished example, and needs a native speaker's review: corrections are welcome.

To add a language (say French, fr; a regional one is fine too, like pt-BR):

Copy each table next to itself as strings-fr.js, and change 'en' in its ns.i18n.add('en', { ... }) line to 'fr'.
Translate the texts. Never change the keys (the left side). Keep every {name} placeholder (move it where your sentence needs it). A text like { one: '{n} reply', other: '{n} replies' } has plural forms: give the forms your language uses (zero, one, two, few, many, other; other is required). A key you leave out shows in English, so a partial translation still works.
Keep button words and row names short: the controls panel's buttons are small. Longer words are drawn smaller to fit, down to 60%, and then cut with "…". Look at your language in VR and pick shorter words where it gets small (Spanish uses "Restablecer" rather than "Predeterminado" for Default).
List the files in manifest.json, each right after its English one:
- src/core/shared/strings-fr.js and src/streamxr/shared/strings-fr.js in the first (page world) entry, and src/core/ui/shared/strings-fr.js and src/streamxr/ui/shared/strings-fr.js in the second (isolated world) entry;
- src/sites/youtube/page/provider/strings-fr.js in the first entry.
Run node tools/sync-shared.js (it makes the two ui/shared/strings-fr.js copies).
Check it in VR: Settings → Language → your language. Panels switch at once; the popup on the video page uses it the next time it opens. Your browser set to that language picks it by default.

The language's name in the Language tab comes from the browser (Intl.DisplayNames), in the language itself ("Español").

Sending it in: while pull requests are paused, open a Translation issue: it has a box for each of the three word lists, so you paste your translated lines straight into it (no files needed), and they'll be added from there. Steps 4-6 are done then.

Code rules

Most of these come from how the project is laid out: read ARCHITECTURE.md before changing structure (it has the folder map, the layers and where common changes go).

No libraries, no build step, no ES modules. Every file is a plain script (function (ns) { ... })(globalThis.__streamxr = globalThis.__streamxr || {}); that adds one piece to the shared namespace. Load order lives in manifest.json. The one exception is vendored third-party code in third_party/ (Google's Material Color Utilities, wrapped as a plain script with its license and a note of the changes); adding another needs agreeing in an issue first.
Keep things where they belong:
- Only src/sites/youtube/page/youtube-*.js read, click or request anything from YouTube. When YouTube's page or data changes, the fix goes there.
- The shell (the core src/core/ and StreamXR src/streamxr/: everything not under src/sites/) never names a site: site code lives in src/sites/<site>/ (YouTube's: src/sites/youtube/), and each site registers its provider in the site registry (src/core/page/sites.js).
- The VR interface (src/core/page/vr-panel/) knows nothing about YouTube: it is a shell meant to drive other sites too (see ARCHITECTURE.md). The chevron panels are built from five styles (vr-panel/styles/: Info, Catalog, Queue, Profile, Options) that draw a plain model and report standard events. YouTube fills them from src/sites/youtube/page/provider/ (one controller per panel, registered in panels.js). A new panel feature goes into a style as a generic option (or a slot), and YouTube's side goes into its controller; a style never gets a YouTube-specific field.
- The shell reaches YouTube only through its provider (src/sites/youtube/page/provider/provider.js, interface at its top): the VR session, the controls panel and format detection ask it, and src/streamxr/page/main.js picks the page's site from the registry.
- Tunable numbers go in the config files (vr-panel/config.js, controllers/config.js, SETTINGS in cinema-screen.js / pause-overlay.js), not scattered through code.
- What each controller input does lives in one place: src/core/shared/controls.js.
- Words shown to the user are never written in the code: add a key to the English table of the part that draws it (src/core/shared/strings-en.js, src/streamxr/shared/strings-en.js, or the site's provider/strings-en.js) and draw ns.i18n.t('key') (see "Translating" and ARCHITECTURE.md, "Words"). The English tables are in American English (color, center, gray), as are the README and the docs users read.
- Colors on the panels are never written in the code either: use a Material 3 color role from src/core/page/vr-panel/tokens.js (TC.<role>, or TA(role, alpha) for a translucent layer). A site's own colors go in its provider's theme.
- Browser-specific code (chrome.*) stays isolated (today: src/sites/youtube/ui/skip-helper.js), so a Firefox port stays possible.
Comment as you go. Every file starts with what it's for. Every function says what it does, and what it returns or which units/pixels it uses when that isn't obvious. Non-obvious steps get a line. Comments describe what the code does now, not its history (that's what git is for). GLSL shaders are explained in a comment above the shader string.
Don't edit generated files: src/core/page/controllers/models.js (made by tools/controller-models/), src/core/ui/shared/ and src/streamxr/ui/shared/ (made by tools/sync-shared.js). After changing anything in src/core/shared/ or src/streamxr/shared/, run node tools/sync-shared.js.
Record user-visible changes in CHANGELOG.md (under the new version), and update ARCHITECTURE.md when you change how things are structured.
Bump version in manifest.json in every pull request that changes the extension, so testers can confirm the reload picked it up.
Keep permissions minimal. The extension asks only for youtube.com. A change that needs more permissions needs a very good reason, discussed in its issue first.
Don't detect headsets by refresh rate (it's a user setting). See the README's "Adding a headset" section for what to use instead.
Match the existing style: 2-space indentation, single quotes, semicolons, const by default, small functions. No reformatting of code you didn't otherwise change.

Before you open the pull request

Two things run on every pull request and push, so you see problems early:

Automatic summary (.github/workflows/pr-summary.yml): fills the bottom of your PR description with the linked issue, the commit history and the changed files, and flags a missing version bump or CHANGELOG entry, new files not in manifest.json, shared files without their regenerated copies, edited generated files, permission changes, and shell code that names a site.
Checks (.github/workflows/pr-checks.yml): node --check on every script, the manifests parse, and node tools/sync-shared.js --check.

Fix what they flag before asking for review. The rest is up to you:

There's an issue for it, and it got a reply agreeing to the change.
It does one thing, and the description says what and why.
Every file you load is listed in manifest.json in the right order.
node --check passes on the files you changed, and node tools/sync-shared.js runs clean if you touched a shared/ folder (src/core/shared/, src/streamxr/shared/).
You tested it in a real VR session (headset, browser, runtime listed in the PR).
Comments are updated for everything you changed.
manifest.json version bumped, and CHANGELOG.md updated.

Forks

The code is MIT, so you're free to fork it and change it for your own use. A few things come with every fork:

Keep the license notices, including the attribution header in src/core/page/controllers/models.js. Those controller models are adapted from Valve's CAD under CC BY-NC-SA 4.0: any fork that keeps them can't be used commercially (see the README's License section).
Please use a different name if your fork changes things substantially, so its bugs aren't reported here.
If your fork adds support for a headset, consider opening an issue here: good, well-structured support can be brought back for everyone.

License of contributions

By contributing, you agree that your contribution is released under this project's MIT license (and, for anything derived from the controller models, CC BY-NC-SA 4.0).

12 KiB Raw Permalink Blame History