jmsr hewel

Use this command to install jmsr:

winget install --id=pigfun.jmsr -e

A high-performance Jellyfin cast receiver that controls an external MPV player.

JMSR - Jellyfin MPV Shim Rust

A high-performance Jellyfin cast receiver that controls an external MPV player.
Built with Tauri v2, Solid.js, and Rust.

Features • Roadmap • Quick Start • Architecture • Troubleshooting

📖 Overview

JMSR allows you to cast media from any Jellyfin client (web, mobile, TV) to your desktop, where it plays in MPV with full support for your custom configurations, shaders, and scripts.

> 💡 Key Philosophy > > JMSR does NOT embed libmpv. Instead, it spawns and controls a standalone MPV process via JSON IPC. This preserves your existing mpv.conf, shader packs (Anime4K, FSR, etc.), and all local customizations without compromise.

✨ Features

Feature	Description
📺 Cast Target	Appears as a controllable device in Jellyfin's cast menu
🚀 External MPV	Full compatibility with your system MPV configuration and shaders
🔒 Persistent Auth	Login once, stay connected with secure token storage
🔄 Auto-Reconnect	Resilient WebSocket connection with exponential backoff strategy
⏭️ Smart Playback	Automatically plays the next episode when the current one finishes
🧠 Series Memory	Remembers audio/subtitle language preferences per TV series
⌨️ Shortcuts	Use `Shift+N` / `Shift+P` directly in MPV to skip episodes
🖥️ System Tray	Runs quietly in the background with quick access controls
🛡️ Type-Safe	100% type-safe Rust-to-TypeScript communication via `tauri-specta`
🍏 Cross-Platform	Native support for Windows, macOS, and Linux

🗺️ Roadmap

Quick Connect - Login via code from another device
Intro Skipper Integration - Auto-skip intros/credits
Full-Featured Client UI - Browse libraries, manage media, and control playback like other Jellyfin clients
Embedded Player - Optional built-in video player without external MPV dependency
MPRIS Support - Linux media player integration for desktop controls

🚀 Enhanced Experience

Discord Rich Presence - Show current playback status on Discord profile
Custom Shaders Manager - Easy toggle for Anime4K, FSR, and other MPV shaders
SyncPlay Support - Watch together with friends via Jellyfin SyncPlay group

🖥️ Desktop Power User

Picture-in-Picture (PiP) - Floating mini-player mode
Global Hotkeys - Customizable shortcuts that work in the background
Offline Mode - Download media for offline playback

🏗️ Architecture

JMSR utilizes a robust three-actor architecture to ensure stability and separation of concerns.

graph LR
    subgraph JMSR[JMSR Desktop App]
        A[<b>Sentinel</b>Tauri GUI]
        B[<b>Bridge</b>Rust Backend]
        A &lt;--&gt; B
    end
    
    B &lt;--&gt;|JSON IPC| C[<b>Player</b>External MPV]
    B &lt;--&gt;|WebSocket + REST| D[<b>Jellyfin Server</b>]
    
    style A fill:#00a4dc,stroke:#333,color:white
    style B fill:#dea584,stroke:#333,color:black
    style C fill:#4c3c69,stroke:#333,color:white
    style D fill:#aa5cc3,stroke:#333,color:white

Sentinel (Tauri GUI): Handles UI, WebSocket connection to Jellyfin, and state management.
Bridge (Rust IPC): Translates commands and manages the external process.
Player (MPV): The standalone media player instance running your config.

🚀 Quick Start

Prerequisites

MPV installed and in PATH

Installation

Download Pre-built Binaries (Recommended)

Download the latest release for your platform from the Releases page:

Platform	Download
Windows	`.msi` (installer) or `.exe` (NSIS)
macOS	`.dmg`
Linux	`.deb` or `.AppImage`

Build from Source

Development prerequisites

Bun (or npm/yarn)
Rust (latest stable)
Tauri CLI: bun add -g @tauri-apps/cli

# Clone the repository
git clone https://github.com/your-username/jmsr.git
cd jmsr

# Install dependencies
bun install

# Build production binaries
bunx tauri build

Binaries will be in src-tauri/target/release/bundle/.

Usage Steps

Launch JMSR from your application menu or terminal.
Authenticate by entering your Jellyfin server URL and credentials.
Cast Media: JMSR will appear as "JMSR" in your Jellyfin client's cast menu.
Enjoy: Media plays in MPV on your desktop with full control syncing.

🛠️ How It Works

Authentication: User logs into Jellyfin and receives an access token.
Registration: JMSR posts capabilities to /Sessions/Capabilities/Full.
WebSocket: Connects to Jellyfin for real-time play state control.
Cast Event: When user casts, Jellyfin sends a Play command.
MPV Control: JMSR spawns MPV (if needed) and sends JSON IPC commands.
Progress: Event-driven progress reporting via MPV property observation.
Sync: Pause/seek/volume commands flow bidirectionally (Jellyfin ↔ MPV).
Auto-Play: Automatically fetches the next episode upon natural file end.

💻 Development

Project Structure

jmsr/
├── src/                    # Solid.js frontend
│   ├── index.tsx          # Entry point
│   ├── bindings.ts        # Auto-generated IPC bindings
│   └── components/        # UI components
├── src-tauri/             # Rust backend
│   ├── src/
│   │   ├── jellyfin/      # Jellyfin client implementation
│   │   └── mpv/           # MPV IPC driver logic
│   └── tauri.conf.json    # Tauri configuration
└── doc/PRD.md            # Product requirements

Commands

Task	Command
Frontend Dev	`bun run dev`
Tauri Dev	`bunx tauri dev`
Build Prod	`bunx tauri build`
Test	`bun run test`
Lint/Format	`bun run check`

📏 Code Conventions

TypeScript: Single quotes, Biome formatting.
Rust: 2-space indent (standard rustfmt.toml).
IPC: Always use typed commands.* from bindings, never raw invoke().
Solid.js: Use createSignal, createResource — NOT React hooks.

➕ Adding a Tauri Command

Add function in src-tauri/src/command.rs with #[tauri::command] and #[specta].
Register in src-tauri/src/lib.rs inside collect_commands![].
Regenerate bindings by running bunx tauri dev.
Import from commands in your TypeScript file.

Technology Stack

Component	Technology
Framework	Tauri v2
Frontend	Solid.js + TypeScript
Backend	Rust
Bundler	Rsbuild
Styling	TailwindCSS
IPC	tauri-specta
Linting	Biome
Testing	Rstest

❓ Troubleshooting

JMSR doesn't appear as cast target

Ensure you're logged in (check Settings page shows "Connected").
Refresh the Jellyfin web page after JMSR connects.
Check Jellyfin Dashboard > Activity for the JMSR session.

MPV doesn't start

Verify MPV is installed: mpv --version.
Check MPV is in PATH (or set explicit path in Settings).
Windows (Scoop): JMSR auto-resolves symlinks, but ensure the shim is valid.
Check Settings > MPV Player for detected path.

Video doesn't play

Check Jellyfin transcoding settings.
Verify network connectivity to Jellyfin server.
Check JMSR log panel (Settings page) for error messages.

Connection lost

JMSR auto-reconnects with exponential backoff (1s → 60s).
Check network connectivity.
Toast notifications will indicate connection status.

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository.
Create a feature branch.
Follow existing code conventions (Biome for TS, rustfmt for Rust).
Run bun run check before committing.
Submit a pull request.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

jellyfin-mpv-shim - The original Python inspiration.
Tauri - For the amazing desktop framework.
MPV - The best media player in existence.