alithw/YTSpoofingStream

YTSpoofingStream

Force 100% Genuine Studio Opus 774 Audio on YouTube via Dual-Stream Synchronization Engine

Read this in other languages: Tiếng Việt.

• ✨ Recent Update Highlights (v0.2.3)
• 🌟 Why YTSpoofingStream?
• 🧠 System Architecture (v0.2.3)
  • 1. Codebase & Directory Structure
  • 2. YouTube's SABR / UMP Infrastructure & Why Legacy Spoofing Fails
  • 3. Dual-Engine 774 Acquisition Pipeline (UmpMseController774 + YTM_HARVESTER)
  • 4. Hardware-Level Descriptor Volume Silencing & Anti-Mute Guard
  • 5. Bit-Perfect 1.0x Master Clock & Lag-Resilient Synchronization
• 🎛️ Operation Modes
• 📊 Full-Track FFT Spectrum Benchmark Results
• 🚀 Installation
• 🌐 Localization & Adding Your Language
• ⚙️ Configuration & Controls
• 🐞 Troubleshooting & FAQ
• 💖 Support / Sponsor the Project
• ⭐ Star History
• 🤝 Contributing & Community
• ⚠️ Disclaimer
• 📄 License

The v0.2.3 release resolves critical player interaction and stream transition bugs, ensuring a seamless listening experience:

• 🎚️ Native Player Volume & Mute Controls Restored: Fixed YouTube's internal audio capability probe (passedProbe) on detached DOM elements, keeping the player volume slider, drag handle, and mute button fully enabled (aria-disabled="false").
• ⏭️ Clean Autoplay Track Transitions: Fixed the track-ending bug where a completed video rewound to 0:00 and replayed for 1–1.5s before advancing. Playback now cleanly pauses at track end and immediately hands off to YouTube's native Autoplay or playlist queue without stutter.
• 🔁 Native Player Loop Support: Respects YouTube player right-click "Loop" and single-track playlist repeat, seamlessly looping both Opus 774 audio and video from 0:00 without triggering premature Autonav.
• ⚡ SABR / UMP Stream Micro-Gap & Duplicate Fetch Resilience: Fixed audio freezes around buffer chunk boundaries (micro-gap stall) via automatic gap-jumping and deduplication in UmpMseController774, preventing infinite reconnect loops and stuck playback.
• 🧠 Direct TV UMP-to-MSE Demuxer (UmpMseController774): Zero-copy in-page UMP/SABR binary demuxer feeding MediaSource (audio/webm; codecs="opus") with 0 MB background iframe RAM overhead.
• 🔇 UI Anti-Mute Guard (774 ↔ 251 Transitions): Eliminates player UI muting when switching between 774 and standard videos.

Across YouTube's ecosystem today, audio quality is strictly tiered:

• Standard YouTube Web (www.youtube.com): Artificially limits audio playback to low-bitrate streams (ITAG 251 Opus at ~145–160kbps with a steep brickwall frequency cutoff at 15–16kHz, or ITAG 140 AAC at ~128kbps), even for paying YouTube Premium subscribers.
• YouTube Music Web Client (music.youtube.com): Despite being a dedicated music service, the web browser version of YouTube Music only serves up to AAC 141 (~256kbps) and does not serve ITAG 774 Opus to desktop web browsers.
• The Only Places YouTube Serves Opus 774: The highest-fidelity unclipped studio sound (ITAG 774 Opus at ~256k–301kbps with full frequency spectrum exceeding 20,000 Hz) is locked away, served exclusively to YouTube Music mobile apps (Android/iOS) and Smart TV Living Room devices (TVHTML5).

1. Direct TVHTML5 UMP/SABR Demuxing: Queries YouTube's TVHTML5 InnerTube endpoint using your linked TV Premium OAuth token, negotiates an unthrottled ITAG 774 stream via Google Video's SABR/UMP protocol, and demuxes the binary Opus chunks directly into an in-page MediaSource buffer.
2. Authenticated YTM Session Harvesting: When TVHTML5 is not linked or a track is YTM-exclusive, an isolated offscreen subframe queries YouTube Music's internal endpoints under emulated high-tier client rules to extract the direct HTTPS Opus 774 URL.
3. Dual-Stream Synchronization Engine (StudioEngine774): Plays the pristine Opus 774 studio stream through a dedicated audio pipeline while silencing the native video's audio at the browser hardware descriptor level, keeping 4K/1080p video and all YouTube UI controls 100% intact.

YTSpoofingStream is built with 100% pure vanilla JavaScript (ES6+)—no bundlers, external libraries, or remote dependencies—for maximum speed, security, and auditability:

YTSpoofingStream/
├── manifest.json               # Manifest V3 configuration, permissions & content script bindings
├── src/
│   ├── background.js           # MV3 Service Worker: InnerTube TV/YTM resolver, OAuth2 & DNR rules
│   ├── inject.js               # MAIN world core: StudioEngine774, UmpMseController774, HUD & sync
│   ├── bridge.js               # ISOLATED world bridge: Bidirectional message relay (MAIN <-> SW)
│   ├── ytm_harvester_cs.js     # MAIN world harvester script inside offscreen YTM subframe
│   ├── harvester.html / .js    # Offscreen document container for YTM Harvester
│   └── popup.html / .js        # Extension popup UI, live status telemetry & i18n controller
├── assets/
│   └── logo.svg, icon*.png     # Extension branding & vector/raster toolbar icons
├── locales/
│   └── en, vi, ja, ru, zh-cn, zh-tw  # Built-in i18n dictionaries & translation template
└── .github/
    └── CONTRIBUTING.md, ...    # Community guidelines, security policy & issue templates

Modern YouTube desktop web streaming uses Google's proprietary SABR (Server-side Adaptive Bitrate) / UMP (Unified Media Protocol):

• The /youtubei/v1/player response on desktop web no longer exposes standalone media URLs in adaptiveFormats. Instead, encrypted/multiplexed binary chunks are pushed over serverAbrStreamingUrl, strictly capped at ITAG 251 (~160kbps Opus) for desktop browsers.
• Why legacy format-replacement extensions fail:
  1. Deleting serverAbrStreamingUrl triggers fatal player error s:80 (HTML5_NO_AVAILABLE_FORMATS_FALLBACK).
  2. Injecting mobile/TV URLs directly into YouTube's native player triggers CORS and token-binding errors s:49 (poToken / client platform mismatch).

To guarantee 100% crash-free playback while delivering bit-perfect ITAG 774, YTSpoofingStream v0.2.3 completely decouples video rendering from studio audio acquisition using two specialized engines:

flowchart TD
    A["YouTube Watch Page / SPA Navigation"] --> B["MAIN World Engine (src/inject.js)"]
    B -->|"Untouched Native Video"| C["YouTube Player (4K/1080p Video Track)"]
    B -->|"RESOLVE_VIDEO (src/bridge.js)"| D["Service Worker (src/background.js)"]

    D -->|"Engine A: TV Authenticated (100ms Cache / 1.5s Live)"| E["TVHTML5 InnerTube (/player)"]
    E -->|"SABR URL + UMP Config"| F["UmpMseController774 (In-Page UMP Demuxer)"]
    F -->|"Part 20/21/22 WebM Opus"| G["MediaSource SourceBuffer (0MB Iframe RAM)"]

    D -->|"Engine B: YTM Harvester (Fallback or YTM Mode)"| H["Offscreen YTM Frame (src/ytm_harvester_cs.js)"]
    H -->|"Direct HTTPS ITAG 774 URL"| I["Direct HTML5 Stream"]

    G --> J["StudioEngine774 (<audio> Master Clock)"]
    I --> J
    J -->|"HTMLMediaElement.prototype.volume = 0"| K["Native Video Silenced at Hardware Level"]
    J -->|"Bit-Perfect 1.0x Studio Opus 774 (>20kHz)"| L["Speaker / DAC Output"]
    C -.->|"Lag-Resilient Clock Alignment"| J

1. Engine A — Direct TV UMP-to-MSE Demuxer (UmpMseController774):
   • Uses your authenticated TVHTML5 OAuth2 token in src/background.js to fetch the TV /player response (100ms fast path on pre-warmed cache, 1500ms cap on live query).
   • Constructs custom Protobuf VideoPlaybackAbrRequest payloads pinned specifically to ITAG 774 (rn, rbuf, ClientAbrState, and FormatId descriptors) and streams the response from Google Video CDN.
   • Parses Google's binary UMP framing in real time inside src/inject.js (Part 20 MEDIA_HEADER, Part 21 MEDIA, Part 22 MEDIA_END, Part 35 NEXT_REQUEST_POLICY, Part 43 SABR_REDIRECT, Part 58 STREAM_PROTECTION_STATUS) and appends the raw WebM/Opus initialization and media segments directly into a browser MediaSource SourceBuffer with automatic sliding-window buffer eviction.
2. Engine B — Authenticated YTM Offscreen Harvester (YTM_HARVESTER):
   • Operates in a lightweight offscreen document (src/harvester.html + src/ytm_harvester_cs.js) backed by scoped Declarative Net Request (DNR) rules to extract direct HTTPS ITAG 774 URLs from YouTube Music Premium sessions.
   • Serves as both the primary engine in YTM_HARVESTER mode and the automatic zero-interruption failover engine in HYBRID_HQ mode.

Setting video.muted = true or video.volume = 0 via standard DOM properties causes the browser to dispatch volumechange events, which tricks YouTube's player into showing a muted speaker icon and persisting "muted": true into localStorage['yt-player-volume'].

YTSpoofingStream v0.2.3 solves this with a two-layer hardware descriptor shield in src/inject.js:

1. Prototype Descriptor Routing: Calls the native HTMLMediaElement.prototype.volume setter (descVolume.set.call(video, 0)) directly on the <video> element while intercepting property getters so YouTube's player UI always sees the user's chosen volume and mute state.
2. Transition Anti-Mute Guard: Suppresses synthetic volumechange events triggered during hardware silencing/restoration (_suppressNextVolumeEvent) and proactively unmutes stale player states when transitioning from a ★ 774 song to a standard 251 video (fallbackTo251()), ensuring the player never gets stuck muted across playlist changes.

StudioEngine774 treats the studio <audio> stream as the continuous master clock:

• Zero Pitch/Resampling Artifacts: audio.playbackRate is strictly locked to video.playbackRate (1.0x native playback)—never micro-adjusted with 0.99x/1.01x pitch warbling.
• SPA Transition Seek Lock: Ignores YouTube's internal SPA reload seeks (timeJump < -0.25s) during the first 1500ms of a track switch or when video.currentTime < 1.5s, preventing songs from restarting a second after playback begins.
• Lag-Resilient Forward Alignment: When backgrounding tabs or heavy CPU/GPU load causes video frames to drop, the audio continues playing smoothly without interruption. Once the video decoder has sufficient buffered data (video.readyState >= 3), the video clock gently aligns forward to match audio.currentTime (drift > 0.35s threshold with a 2.5s cooldown).

Comprehensive 1x real-time full-duration tests across 4 diverse benchmark tracks with extension ON (Studio 774) vs OFF (Hard Disabled in Chrome Settings):

Observation: Standard ITAG 251 applies a steep low-pass brickwall filter cutoff at 15.5kHz–16kHz. YTSpoofingStream v0.2.3 delivers unclipped spectral density up to 21kHz+, resulting in noticeably clearer cymbals, vocals, and soundstage.

1. Download or clone the repository:
   • For standard users (No Git required):
     Click the green Code button at the top of this repository and select Download ZIP (or visit Releases, scroll down to the bottom of the latest release under Assets, and download Source code (zip)). Extract the downloaded ZIP file to a folder on your computer.
   • For developers (using Git):

     git clone https://github.com/alithw/YTSpoofingStream.git

2. Open chrome://extensions/ and toggle on Developer mode in the top-right corner.
3. Click Load unpacked and select the root YTSpoofingStream folder (the folder containing manifest.json).
4. Open YouTube, ensure you are logged into your Premium account, and verify the ★ 774 badge in the player control bar!

YTSpoofingStream supports 6 languages out of the box (English, Tiếng Việt, 日本語, Русский, 简体中文, and 繁體中文) with automatic browser language detection.

We welcome community translations! You can easily add your native language in 3 steps:

1. Copy the Template:
   Duplicate locales/template.json and rename it to your ISO 639-1 language code (e.g. es.json for Spanish, ko.json for Korean, de.json for German, fr.json for French) inside the locales/ directory.
2. Translate the Strings:
   • Fill in the _meta section with your language details and your GitHub username for credit.
   • Translate each value accurately while keeping placeholder tokens ({version}, {method}, {label}, {error}, {url}) and symbols (★, •, ↻, ⟳) intact.
3. Register & Submit:
   • Add your language <option value="code">Language Name</option> to the #langSelect dropdown in src/popup.html.
   • Submit a Pull Request (PR)!

• Enable Extension: Master toggle switch. When turned off, completely unhooks all listeners and restores standard native YouTube playback.
• Operation Mode: Switch between HYBRID_HQ (Recommended), YTM_HARVESTER, or TV_HEADLESS.
• Audio-Only Mode: Pauses video element rendering and hides the video canvas (also accessible via the headphone icon right next to the ★ 774 badge in the player bar) to save RAM & GPU/CPU while listening to studio audio.
• Auto-reload page on change: Automatically reloads the active YouTube tab when switching operation modes.
• Stats for Nerds Override (774 Spoof): Displays live ITAG 774 Opus codec and bitrate telemetry inside YouTube's native Stats for Nerds overlay.
• TVHTML5 Login: OAuth2 device-code activation portal for linking your YouTube Premium account to the TVHTML5 engine.

Q: Why does the badge show 251 instead of ★ 774?
A: Some videos (such as non-music vlogs, gaming streams, or older uploads) are encoded by YouTube exclusively up to ITAG 251. The extension strictly verifies stream authenticity and falls back cleanly to native 251 audio if no genuine 774 stream exists.

Q: Does this extension affect YouTube Music (music.youtube.com)?
A: Content scripts are excluded from hooking the foreground music.youtube.com UI, however, if you actively browse music.youtube.com in a foreground tab, we recommend switching Enable Extension: OFF in the popup so background Declarative Net Request (DNR) rules for the YTM Harvester do not interfere with foreground music.youtube.com requests. Note that music.youtube.com on desktop browsers only serves up to AAC 141 (~256kbps)—to listen to genuine Opus 774, play your music directly on www.youtube.com with YTSpoofingStream enabled!

If YTSpoofingStream enhances your music listening experience on YouTube, consider supporting its active development and maintenance:

You can sponsor directly via GitHub Sponsors (github.com/sponsors/alithw) or buy a coffee on Ko-fi (ko-fi.com/alithw). Every contribution helps maintain and update the engine against YouTube's frequent backend changes! ☕✨

Contributions of all kinds are welcome! Whether you are reporting a bug, proposing new stream extraction strategies, or submitting code improvements, please read our community guidelines:

• 📘 Contributing Guide (CONTRIBUTING.md): Local development setup, codebase architecture map, vanilla ES6+ coding standards, and PR submission checklist.
• 📜 Code of Conduct (CODE_OF_CONDUCT.md): Our standards for a welcoming, constructive, and harassment-free community (Contributor Covenant 2.1).
• 🔒 Security Policy (SECURITY.md): Guidelines for responsibly disclosing vulnerabilities.
• 🐛 Report a Bug: Use our structured issue form with video details and player console logs.
• 💡 Request a Feature: Share ideas to enhance audio streaming and client compatibility.

• Independent Project: YTSpoofingStream is an independent, open-source project and is not affiliated, associated, authorized, endorsed by, or in any way officially connected with YouTube, Google LLC, or Alphabet Inc. The official YouTube website can be found at https://www.youtube.com. "YouTube" and "YouTube Music" are registered trademarks of Google LLC.
• No DRM Circumvention: This extension does not bypass Widevine DRM, crack protected content, or provide unauthorized downloads/piracy. It strictly functions within legitimate, authenticated browser sessions to route streams already authorized for the user.
• Educational & Personal Use: This software is provided for educational and personal research purposes only. Use of this software is at your own discretion and responsibility in compliance with YouTube's Terms of Service. The software is provided "as is", without warranty of any kind.

Distributed under the Apache License 2.0. See LICENSE for complete details.