YouTube Now Playing for Senpai by Ztjuh

Plugin overview
This add-on is a Firefox WebExtension that bridges YouTube playback information into Linux’s desktop media ecosystem, specifically MPRIS, so that Senpai can query the currently playing YouTube title via its /np feature.

The core idea is simple:

The extension watches the active YouTube page
When a video is playing, it extracts the title and URL
It sends that data to a local native messaging host
The host registers itself as a D-Bus/MPRIS media player named youtube_senpai
Senpai can then call the player over DBus and read the current metadata
This makes the browser appear to the desktop environment as a media player, even though it is really just a WebExtension feeding metadata to a local Linux bridge.

Technical architecture
1) Extension manifest
The add-on is declared in manifest.json. It has:

Manifest version 3
Native Messaging permission
Host permissions for YouTube pages
A content script restricted to YouTube watch pages
A background script that opens a native messaging connection
The file is intentionally minimal and only exposes the browser-side functionality required to collect and forward playback metadata.

2) Content script
The logic in content.js runs inside the page and listens for YouTube playback events.

What it does:

Finds the current <video> element
Confirms the video is actually playing
Reads the page title or YouTube metadata title
Ensures the page is a watch page and not some other YouTube page
Debounces updates so it does not spam the native host
Stores the last URL to avoid duplicate sends for the same video
It uses:

MutationObserver to watch for DOM changes
the play event
yt-navigate-finish to detect navigation without full reload
This means it reacts naturally to YouTube SPA navigation and track changes.

3) Background script
The browser background script in background.js is the glue layer between the page script and the native host.

It does:

listens for messages of type now-playing
opens a connection to the native host with browser.runtime.connectNative("youtube_senpai_bridge")
sends JSON payloads containing:
type
title
url
The native host is a long-lived process created by Firefox and kept open for message exchange. This is the standard Native Messaging flow for Firefox add-ons.

4) Native Messaging bridge
The Python bridge at youtube_senpai_bridge.py is the Linux-side integration point.

It performs several important tasks:

reads messages from Firefox over stdin/stdout using the Native Messaging protocol
validates the incoming payload
registers a DBus service named org.mpris.MediaPlayer2.youtube_senpai
exports a minimal MPRIS player interface
exposes properties such as:
PlaybackStatus
Metadata
Identity
DesktopEntry
updates title and URL whenever a new YouTube video is reported
makes the player appear as an active media player to desktop tools like playerctl and Senpai
The MPRIS implementation is intentionally lightweight and exposes only the subset needed for status lookup. It does not implement full media controls like seeking or skipping, because the project only needs to expose “what is playing now”.

Data flow
Here is the flow in plain terms:

The user opens a YouTube watch page
The content script sees the video is playing
It reads the current title and watch URL
It sends a message to the background script
The background script forwards that to the native host
The Python bridge updates its DBus/MPRIS metadata
Senpai reads the metadata through MPRIS using /np
The active IRC buffer receives the current YouTube title
Why this is useful
This is useful because Senpai can show the current playing media without needing direct YouTube API access or custom browser integration. It turns the browser into a system-level media source using standard Linux protocols.

It is particularly suited for:

desktop Linux environments
Senpai IRC workflows
plugin-style “now playing” integrations
users who want to expose browser playback to other apps without a custom browser UI
Security and scope
The extension is intentionally scoped:

it only runs on YouTube watch pages
it only reads the current title and URL
it does not send arbitrary data to remote servers
it only communicates with the locally installed native host
the native host only exposes metadata through MPRIS and does not perform network requests itself
This keeps the add-on minimal and reduces the risk of privacy issues.

Summary
This project is effectively a Linux media bridge for Firefox:

Firefox page → capture current YouTube title and URL
Firefox add-on → send metadata via Native Messaging
Python host → expose as MPRIS player youtube_senpai
Senpai → read current title with /np