If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mpvnet-player/mpv.net shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 3mo ago
• 6 active contributors
• GPL-2.0 licensed
• ⚠ Single-maintainer risk — top contributor 80% of recent commits
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mpvnet-player/mpv.net repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mpvnet-player/mpv.net.

What it runs against: a local clone of mpvnet-player/mpv.net — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mpvnet-player/mpv.net | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 119 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mpvnet-player/mpv.net. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mpvnet-player/mpv.net.git
#   cd mpv.net
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mpvnet-player/mpv.net and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mpvnet-player/mpv.net(\\.git)?\\b" \\
  && ok "origin remote is mpvnet-player/mpv.net" \\
  || miss "origin remote is not mpvnet-player/mpv.net (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/MpvNet.Windows/Program.cs" \\
  && ok "src/MpvNet.Windows/Program.cs" \\
  || miss "missing critical file: src/MpvNet.Windows/Program.cs"
test -f "src/MpvNet.Windows/Conf.cs" \\
  && ok "src/MpvNet.Windows/Conf.cs" \\
  || miss "missing critical file: src/MpvNet.Windows/Conf.cs"
test -f "src/MpvNet.Windows/Settings.cs" \\
  && ok "src/MpvNet.Windows/Settings.cs" \\
  || miss "missing critical file: src/MpvNet.Windows/Settings.cs"
test -f "src/MpvNet.Windows/WPF/ConfWindow.xaml.cs" \\
  && ok "src/MpvNet.Windows/WPF/ConfWindow.xaml.cs" \\
  || miss "missing critical file: src/MpvNet.Windows/WPF/ConfWindow.xaml.cs"
test -f "src/MpvNet.Windows/UI/Theme.cs" \\
  && ok "src/MpvNet.Windows/UI/Theme.cs" \\
  || miss "missing critical file: src/MpvNet.Windows/UI/Theme.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 119 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~89d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mpvnet-player/mpv.net"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

mpv.net is a Windows GUI wrapper around libmpv that brings the powerful, lightweight mpv media player to Windows with a modern customizable interface. It enables users to play videos, audio, and images with advanced features like GPU video decoding (DXVA2), high-quality video scaling, color management, HDR support, and scripting (Lua/JavaScript) — all while maintaining mpv compatibility so the official mpv manual largely applies. Multi-project C# solution: src/MpvNet.Windows/ is the main WinForms application (Conf.cs for configuration, GuiCommand.cs for commands, FileAssociation.cs for integration); src/MpvNet.Extension/ provides an extension framework with ExampleExtension as a template. Localization lives in lang/ with .po files and PowerShell build scripts (update-po-and-pot-files.ps1). Native interop lives in src/MpvNet.Windows/Native/.

Windows users (videophiles, power users, developers) who want a lightweight, feature-rich media player with extensive customization, scripting capabilities, and audio/video enthusiast features. Contributors are typically C# developers and mpv ecosystem maintainers adding GUI features or extending the libmpv bindings.

Actively developed and production-ready: the repository has significant GitHub engagement (closed issues/PRs badges, multiple releases tagged), a comprehensive manual (docs/manual.md), internationalization support (11 language .po files), and structured CI/CD (GitHub Actions workflows in .github/workflows). However, the build workflow is noted as 'currently flawed' which suggests recent or ongoing fixes.

Single-maintainer risk (stax76 appears as primary owner) and the broken CI/CD pipeline (.github/workflows marked 'currently flawed') could delay releases or miss regressions. Dependency on libmpv (external C library) and FFmpeg hwaccel APIs introduces platform-specific stability concerns. No visible test suite in the file structure suggests limited automated regression detection.

The repository has GitHub Actions workflows defined but marked as flawed, indicating active work on CI/CD. Multiple closed PRs and issues suggest steady maintenance. The comprehensive docs/changelog.md and privacy.md suggest recent documentation efforts. No specific open milestones are visible in the file list, but the .editorconfig and Directory.Build.props setup indicates modernization of the build system.

Clone the repository and open src/MpvNet.Windows/MpvNet.Windows.csproj in Visual Studio or use dotnet build src/MpvNet.Windows/MpvNet.Windows.csproj. Dependencies are managed via Directory.Packages.props (centralized package management). PowerShell scripts in lang/ handle localization builds (e.g., powershell -ExecutionPolicy Bypass -File lang/update-po-and-pot-files.ps1).

Daily commands: Load src/MpvNet.Windows.sln in Visual Studio and build/run MpvNet.Windows project. For CLI testing, the app supports mpv command-line arguments per the README. PowerShell scripts in lang/ regenerate .po and .mo translation files: powershell lang/update-po-and-pot-files.ps1.

• src/MpvNet.Windows/Program.cs — Entry point for the entire WPF application; initializes mpv.net and bootstraps the UI framework.
• src/MpvNet.Windows/Conf.cs — Core configuration management system that loads, validates, and applies mpv settings and user preferences.
• src/MpvNet.Windows/Settings.cs — Settings persistence layer handling serialization/deserialization of application state and user options.
• src/MpvNet.Windows/WPF/ConfWindow.xaml.cs — Primary configuration UI window; demonstrates WPF binding patterns and controls architecture used throughout the app.
• src/MpvNet.Windows/UI/Theme.cs — Theme engine responsible for loading and applying customizable color themes across the entire GUI.
• src/MpvNet.Windows/GuiCommand.cs — Command routing system that bridges user actions from the GUI to mpv player control and settings changes.
• src/MpvNet.Extension/ExampleExtension/ExampleExtension.cs — Extension API contract; shows how third-party developers can extend mpv.net functionality without modifying core.

Add a New Configuration Option

1. Define the configuration key and default value in src/MpvNet.Windows/Conf.cs by adding a new property or entry in the config dictionary. (src/MpvNet.Windows/Conf.cs)
2. Create a UI control (ComboBoxSettingControl, StringSettingControl, or OptionSettingControl) in the WPF Controls folder to allow user editing. (src/MpvNet.Windows/WPF/Controls/)
3. Add the control instance to ConfWindow.xaml with proper data binding to expose the setting in the configuration UI. (src/MpvNet.Windows/WPF/ConfWindow.xaml)
4. Update the translation template lang/source.pot and generate .po files for all supported languages. (lang/source.pot)

Add a New Theme Color Scheme

1. Create a new theme file in a subdirectory or define new color entries following the existing theme.txt format. (src/MpvNet.Windows/Resources/theme.txt)
2. Modify Theme.cs to load and parse the new color definitions, registering them in the theme manager. (src/MpvNet.Windows/UI/Theme.cs)
3. Add a ComboBoxSettingControl in ConfWindow.xaml to allow users to select the new theme. (src/MpvNet.Windows/WPF/ConfWindow.xaml)

Create a New WPF Extension Plugin

1. Copy and customize ExampleExtension.csproj to create your extension project with the proper class library structure. (src/MpvNet.Extension/ExampleExtension/ExampleExtension.csproj)
2. Implement a class that conforms to the extension API contract shown in ExampleExtension.cs. (src/MpvNet.Extension/ExampleExtension/ExampleExtension.cs)
3. Build your extension; mpv.net will discover it in the plugins folder and load it at runtime. (src/MpvNet.Extension/)

Add a New Global Hotkey

1. Add a new command entry to the GuiCommand enum to represent the hotkey action. (src/MpvNet.Windows/GuiCommand.cs)
2. Register the hotkey in GlobalHotkey.cs and map it to the corresponding GUI command and mpv operation. (src/MpvNet.Windows/UI/GlobalHotkey.cs)
3. Allow users to customize the hotkey by adding a configuration option in Conf.cs and a UI control in ConfWindow.xaml. (src/MpvNet.Windows/Conf.cs)

• WPF (Windows Presentation Foundation) — Native Windows UI framework enabling modern, themeable GUI with XAML data binding; tightly integrates with Win32 and Windows ecosystem features.

libmpv library and FFmpeg binaries must be present at runtime (not vendored in repo); the build likely expects them in PATH or bundled separately. The .po translation files in lang/ require gettext/Transifex tooling (.tx/config suggests Transifex integration) — modifying translations without the toolchain may cause sync issues. WinForms likely uses embedded resources for themes/icons (.editorconfig suggests strict line-ending handling across platforms). The 'currently flawed' CI status means the automated build pipeline is broken — manual local testing is essential before committing.

• libmpv (C API for media player) — mpv.net's entire playback engine is powered by libmpv; understanding its command/property model and event loop is essential for implementing new player features.
• DXVA2 (DirectX Video Acceleration 2) — Key feature listed in mpv.net: GPU-accelerated video decoding on Windows; understanding DXVA2 helps optimize performance and troubleshoot decode issues.
• P/Invoke (Platform Invoke) — mpv.net uses P/Invoke extensively (src/MpvNet.Windows/Native/) to call native Windows APIs for file associations and system integration; essential for Windows-specific features.
• gettext / .po localization files — mpv.net supports 11 languages via .po files (lang/po/*.po) and Transifex integration; contributing involves understanding GNU gettext message catalogs.
• libmpv command/property IPC model — mpv.net communicates with libmpv via command execution and property observation (GuiCommand.cs); the IPC paradigm differs from DirectShow and is critical to feature implementation.
• WinForms (Windows Forms) — The GUI framework used for mpv.net's 'modern GUI with customizable color themes'; understanding WinForms layout, theming, and event handling is needed for UI work.
• Lua/JavaScript scripting in mpv — mpv.net inherits mpv's scripting capabilities; users and contributors extend features via Lua or JavaScript scripts; understanding the scripting API unlocks advanced customization.

• mpv-player/mpv — The upstream media player engine; mpv.net is built entirely on libmpv from this project and inherits its command set and philosophy.
• stax76/awesome-mpv — Community-curated collection of mpv scripts and extensions; directly referenced in mpv.net README and shows the ecosystem of Lua/JavaScript add-ons mpv.net inherits.
• yt-dlp/yt-dlp — Optional dependency for media streaming support in mpv.net (mentioned in README as required for built-in media streaming), users must install separately.
• VideoLAN/vlc — Alternative cross-platform media player with GUI; shares similar feature set (codec support, scripting) but uses DirectShow/MF rather than libmpv.
• mpvnet-player/mpv-android — Android port of mpv; demonstrates how libmpv bindings extend to other platforms, relevant for understanding libmpv's portability model.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for automated .NET builds and tests

The .github/workflows directory is marked as 'currently flawed' and contains build.yml. The repo is a C# .NET project (MpvNet.Windows.csproj, Directory.Build.props) but lacks a reliable CI pipeline. A new contributor could fix/enhance the build workflow to automatically compile the solution, run tests, and validate PRs on Windows runners, ensuring code quality before merge.

• [ ] Review current .github/workflows/build.yml and identify flaws
• [ ] Create a robust workflow that: builds src/MpvNet.Windows/MpvNet.Windows.csproj, runs any existing tests, and validates on Windows runner
• [ ] Add workflow triggers for push to main and pull requests
• [ ] Test workflow locally or via fork to ensure it passes for current codebase
• [ ] Document workflow in README.md or CONTRIBUTING.md (if missing)

Add unit tests for Conf.cs and Settings.cs configuration management

The repo has critical configuration files (src/MpvNet.Windows/Conf.cs and src/MpvNet.Windows/Settings.cs) that handle app settings, themes, and user preferences, but no visible test files in the structure. These classes are central to the application and deserve comprehensive unit test coverage to prevent regressions when configuration logic changes.

• [ ] Create src/MpvNet.Windows.Tests/ConfTests.cs with tests for config parsing, validation, and serialization
• [ ] Create src/MpvNet.Windows.Tests/SettingsTests.cs with tests for settings load/save, defaults, and edge cases
• [ ] Test integration with resources like src/MpvNet.Windows/Resources/theme.txt and editor_conf.txt
• [ ] Use xUnit or MSTest framework (align with project conventions)
• [ ] Update MpvNet.Windows.csproj to include test project in solution

Document Windows-specific GUI implementation in docs/manual.md (GUI section)

The manual.md exists but the README snippet is truncated mid-sentence ('mpv.net supports mpvs command li...'). The codebase has significant WPF/UI code (src/MpvNet.Windows/WPF/, src/MpvNet.Windows/UI/) but these features are not documented. A new contributor could document the GUI-specific features, keybindings, theme customization, and differences from headless mpv in the manual.

• [ ] Review src/MpvNet.Windows/UI/GlobalHotkey.cs and src/MpvNet.Windows/UI/Theme.cs to understand hotkey/theme system
• [ ] Review src/MpvNet.Windows/Resources/theme.txt to understand theme customization format
• [ ] Add new section to docs/manual.md: 'GUI Features' covering theme customization, global hotkeys, and WPF-specific settings
• [ ] Add examples for common customizations (colors, fonts, keybindings)
• [ ] Update README.md to complete the truncated 'Command Line Interface' section and link to GUI documentation

• Add unit tests for src/MpvNet.Windows/Conf.cs configuration parsing to catch regressions when users edit config files — currently no visible test project exists in the structure.
• Document the native interop layer (src/MpvNet.Windows/Native/) with code comments and a guide in docs/ explaining how P/Invoke bindings map to Windows APIs, reducing friction for contributors adding new features.
• Fix the broken .github/workflows/build.yml CI pipeline marked 'currently flawed' by testing locally, validating PowerShell script execution, and ensuring libmpv/FFmpeg binary discovery works in the GitHub Actions environment.

The mpv.net codebase demonstrates moderate security posture for a Windows media player application. Key concerns include: (1) native Windows API usage requiring careful P/Invoke security practices, (2) configuration file parsing that needs strict input validation, and (3) CI/CD pipeline configuration issues. The application's attack surface is relatively limited for a media player, but Windows API interactions and file I/O operations require careful security review. No hardcoded credentials were identified in the provided file listing, and the project structure suggests reasonable separation of concerns. Recommendations focus on input validation hardening, secure configuration handling, and strengthening the build pipeline security.

• Medium · Potential Unsafe Windows API Usage — src/MpvNet.Windows/Native/WinApi.cs, src/MpvNet.Windows/Native/Taskbar.cs. The codebase includes Windows API wrappers (WinApi.cs, Taskbar.cs) that interact with native Windows functionality. Without detailed code review, there's a risk of improper P/Invoke declarations, buffer overflows, or unsafe marshaling that could lead to privilege escalation or code injection. Fix: Conduct a thorough security review of all P/Invoke declarations. Ensure proper validation of input sizes, use SafeHandle for resource management, and validate all data from external sources before passing to unmanaged code.
• Medium · Global Hotkey Registration Without Validation — src/MpvNet.Windows/UI/GlobalHotkey.cs. The GlobalHotkey.cs file manages global hotkey registration. If hotkey bindings are not properly validated or sanitized, particularly when loaded from configuration files, this could lead to unintended command execution or privilege escalation. Fix: Implement strict validation for hotkey bindings. Whitelist allowed hotkey combinations, validate configuration file parsing, and implement proper error handling for invalid inputs.
• Medium · Configuration File Parsing Without Input Validation — src/MpvNet.Windows/Conf.cs, src/MpvNet.Windows/Settings.cs. Configuration files (Conf.cs, Settings.cs) are loaded from disk and parsed. If parsing doesn't properly validate or sanitize values, malicious configuration files could lead to code injection, path traversal, or command execution. Fix: Implement strict schema validation for all configuration files. Use typed configuration parsers, sanitize all string inputs, implement bounds checking for numeric values, and validate file paths to prevent directory traversal attacks.
• Low · Potential Information Disclosure via Exception Handling — src/MpvNet.Windows/ (throughout). The codebase includes exception handling in various components. Detailed error messages or stack traces exposed to users could reveal sensitive information about the application's internal structure or file paths. Fix: Implement centralized exception handling that logs detailed errors securely but only displays generic user-friendly messages. Never expose file paths, code structure, or internal details in user-facing error messages.
• Low · Missing Security Policies in GitHub Workflows — .github/__workflows__/build.yml. The GitHub workflow file (.github/workflows/build.yml) is noted as 'currently flawed'. CI/CD pipeline issues could lead to compromised builds, unauthorized releases, or supply chain attacks. Fix: Review and harden the build workflow. Implement: pinned dependency versions, code signing for releases, OIDC-based authentication, branch protection rules, and approval requirements for deployments.
• Low · File Association Handling Without Validation — src/MpvNet.Windows/FileAssociation.cs. FileAssociation.cs handles file type associations with the system. Improper validation could allow registry manipulation or unexpected file type associations. Fix: Validate all file extensions and registry paths. Use Windows API safely, implement proper permission checks, and log all file association changes for auditing purposes.
• Low · Resource Files Not Reviewed for Security Content — src/MpvNet.Windows/Resources/. Theme and editor configuration resource files (theme.txt, editor_conf.txt) are embedded resources. If these can be modified or if parsing is unsafe, it could impact security. Fix: Ensure resource files are read-only and their integrity is verified at runtime. Implement schema validation for any configuration data parsed from these files.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.