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/Tyrrrz/YoutubeDownloader 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.

GO — Healthy across all four use cases

• Last commit 6d ago
• 7 active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits
• ⚠ 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 Tyrrrz/YoutubeDownloader repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tyrrrz/YoutubeDownloader.

What it runs against: a local clone of Tyrrrz/YoutubeDownloader — 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 Tyrrrz/YoutubeDownloader | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch prime exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tyrrrz/YoutubeDownloader. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tyrrrz/YoutubeDownloader.git
#   cd YoutubeDownloader
#
# 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 Tyrrrz/YoutubeDownloader and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "YoutubeDownloader/Program.cs" \\
  && ok "YoutubeDownloader/Program.cs" \\
  || miss "missing critical file: YoutubeDownloader/Program.cs"
test -f "YoutubeDownloader/ViewModels/MainViewModel.cs" \\
  && ok "YoutubeDownloader/ViewModels/MainViewModel.cs" \\
  || miss "missing critical file: YoutubeDownloader/ViewModels/MainViewModel.cs"
test -f "YoutubeDownloader.Core/Downloading/VideoDownloader.cs" \\
  && ok "YoutubeDownloader.Core/Downloading/VideoDownloader.cs" \\
  || miss "missing critical file: YoutubeDownloader.Core/Downloading/VideoDownloader.cs"
test -f "YoutubeDownloader.Core/Resolving/QueryResolver.cs" \\
  && ok "YoutubeDownloader.Core/Resolving/QueryResolver.cs" \\
  || miss "missing critical file: YoutubeDownloader.Core/Resolving/QueryResolver.cs"
test -f "YoutubeDownloader/Services/SettingsService.cs" \\
  && ok "YoutubeDownloader/Services/SettingsService.cs" \\
  || miss "missing critical file: YoutubeDownloader/Services/SettingsService.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 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
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/Tyrrrz/YoutubeDownloader"
  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).

YoutubeDownloader is a desktop application (built with Avalonia UI) that downloads videos, playlists, and channels from YouTube in multiple formats and qualities. It uses YoutubeExplode (a reverse-engineered YouTube API client) under the hood to fetch metadata and streams, and FFmpeg to transcode downloaded content into user-preferred formats. The app supports keyword search, quality preferences, and metadata tagging via MusicBrainz integration. Layered architecture: YoutubeDownloader.Core contains domain logic split into Downloading/ (VideoDownloader, FFmpeg wrapper, quality/format preferences), Resolving/ (QueryResolver for playlist/video/channel detection), and Tagging/ (MediaTagInjector with MusicBrainz client). YoutubeDownloader/ is the Avalonia WPF-like UI with Framework/ (DialogManager, ViewModelBase, SnackbarManager), Converters/, and Localization/. Shared dependencies via Directory.Build.props and Directory.Packages.props (centralized package management).

End users who want a GUI-based YouTube downloader without browser dependencies or API keys. Also relevant to developers extending media downloading capabilities or building on YoutubeExplode.

Production-ready with active maintenance (status badge shows 'maintenance' phase). The codebase is well-structured with a clear separation between Core (YoutubeDownloader.Core) and UI (YoutubeDownloader/), CI/CD via GitHub Actions (main.yml), and a release workflow. The project has substantial GitHub presence (implied by downloads badge and community Discord).

Single maintainer (Tyrrrz) introduces continuity risk. YouTube reverse-engineering is inherently fragile—API changes break frequently, requiring rapid responses. The codebase depends on YoutubeExplode (external dependency also by same author) and FFmpeg (system binary), both potential single points of failure. No visible test files in the provided structure, which increases regression risk on complex scenarios (quality fallback, encoding edge cases).

Repository is in maintenance mode (not active development). The GitHub Actions workflow (main.yml) and release workflow suggest automated builds and releases are active. Dependabot configuration (.github/dependabot.yml) indicates automated dependency updates. No specific current sprint or milestone visible in provided data, but the presence of localization files and tagging infrastructure suggests previous feature richness is being sustained.

git clone https://github.com/Tyrrrz/YoutubeDownloader.git
cd YoutubeDownloader
dotnet restore
dotnet build YoutubeDownloader.sln
dotnet run --project YoutubeDownloader

Note: FFmpeg must be installed separately (system PATH or bundled).

Daily commands:

dotnet run --project YoutubeDownloader --configuration Release

Or open YoutubeDownloader.slnx in Visual Studio 2022+ and press F5. Requires .NET 8 SDK and FFmpeg on PATH.

• YoutubeDownloader/Program.cs — Entry point for the Avalonia application; sets up dependency injection and launches the main window.
• YoutubeDownloader/ViewModels/MainViewModel.cs — Root view model orchestrating dashboard, downloads, and dialog management; core application logic flow.
• YoutubeDownloader.Core/Downloading/VideoDownloader.cs — Core business logic for downloading videos; handles quality selection, file naming, and FFmpeg integration.
• YoutubeDownloader.Core/Resolving/QueryResolver.cs — Resolves YouTube queries (URLs, IDs, playlists) into video metadata; critical for input validation.
• YoutubeDownloader/Services/SettingsService.cs — Manages application configuration, authentication cookies, and user preferences persistence.
• YoutubeDownloader.Core/Downloading/FFmpeg.cs — Wrapper around FFmpeg executable for video transcoding and format conversion; external process lifecycle.
• YoutubeDownloader/Framework/ViewManager.cs — Centralizes view/viewmodel registration and navigation; enables MVVM pattern across the desktop UI.

Add a new video quality preference

1. Define the preference constant in VideoQualityPreference.cs (e.g., HighestFrameRate) (YoutubeDownloader.Core/Downloading/VideoQualityPreference.cs)
2. Add selection logic in VideoDownloadOption to score formats matching the new preference (YoutubeDownloader.Core/Downloading/VideoDownloadOption.cs)
3. Add a UI radio button or dropdown option in DownloadSingleSetupView.axaml (YoutubeDownloader/Views/Dialogs/DownloadSingleSetupView.axaml)
4. Add display string converter in VideoQualityPreferenceToStringConverter.cs (YoutubeDownloader/Converters/VideoQualityPreferenceToStringConverter.cs)
5. Update DownloadSingleSetupViewModel to bind the new preference option (YoutubeDownloader/ViewModels/Dialogs/DownloadSingleSetupViewModel.cs)

Add a new language localization

1. Create new partial LocalizationManager file (e.g., LocalizationManager.Italian.cs) with translated resource strings (YoutubeDownloader/Localization/LocalizationManager.Italian.cs)
2. Add language enum value to Language.cs (YoutubeDownloader/Localization/Language.cs)
3. Register language in LocalizationManager.cs GetAvailableLanguages() and resource switch statement (YoutubeDownloader/Localization/LocalizationManager.cs)
4. Add language option to SettingsView.axaml language selection dropdown (YoutubeDownloader/Views/Dialogs/SettingsView.axaml)

Add metadata injection for a new file type

1. Extend MediaFile.cs to support new container type properties (e.g., .webm metadata fields) (YoutubeDownloader.Core/Tagging/MediaFile.cs)
2. Add tagging logic for the new format in MediaTagInjector.cs (use appropriate metadata library) (YoutubeDownloader.Core/Tagging/MediaTagInjector.cs)
3. Update VideoDownloadOption.cs to include new format in format selection (YoutubeDownloader.Core/Downloading/VideoDownloadOption.cs)
4. Test with DownloadSingleSetupViewModel selecting the new format (YoutubeDownloader/ViewModels/Dialogs/DownloadSingleSetupViewModel.cs)

Add a new download option/feature to the UI

1. Add property to DownloadSingleSetupViewModel (e.g., IncludeSubtitles property with ICommand handler) (YoutubeDownloader/ViewModels/Dialogs/DownloadSingleSetupViewModel.cs)
2. Add checkbox/toggle control to DownloadSingleSetupView.axaml bound to the new property (YoutubeDownloader/Views/Dialogs/DownloadSingleSetupView.axaml)
3. Implement feature logic in VideoDownloader.cs (e.g., subtitle extraction in download pipeline) (YoutubeDownloader.Core/Downloading/VideoDownloader.cs)
4. Persist setting in SettingsService.cs (add to settings model and save/load methods) (YoutubeDownloader/Services/SettingsService.cs)

1. FFmpeg dependency: YoutubeDownloader.Core/Downloading/FFmpeg.cs calls System.Diagnostics.Process on 'ffmpeg' binary—must be installed on system PATH or bundled; Windows/macOS/Linux have different binary names. 2) YoutubeExplode fragility: YouTube API reverse-engineering breaks without notice; YoutubeExplode NuGet package must be kept up-to-date. 3) MusicBrainz rate limiting: MusicBrainzClient makes HTTP calls to external service—no visible caching or backoff strategy, bulk operations may hit rate limits. 4) Localization paths: Localization/ directory implies multi-language support via resource files—new UI strings require entries in all language files or defaults may show English. 5) Avalonia platform quirks: Cross-platform UI means testing needed on Windows/Linux/macOS; file path handling (YoutubeDownloader/Utils/Http.cs suggests HTTP downloads) must account for OS differences.

• Reverse-engineering YouTube API — YoutubeDownloader's entire foundation relies on YoutubeExplode reverse-engineering YouTube's undocumented APIs; understanding why this is fragile (YouTube changes break it) and how authentication/signatures work is critical for maintenance.
• MVVM (Model-View-ViewModel) Pattern — The entire UI layer (Framework/ViewModelBase.cs, DialogViewModelBase) and all UI interactions follow MVVM with data binding; contributors must understand INotifyPropertyChanged, command binding, and separation of concerns.
• FFmpeg Transcoding & Codec Selection — VideoDownloader.cs must invoke FFmpeg with correct codec arguments based on user quality preference and container format; understanding video codecs (H.264, VP9, AV1), audio codecs (AAC, Opus), and bitrate control is essential for quality/performance optimization.
• Adaptive Bitrate Streaming (DASH) — YouTube serves video and audio as separate streams (DASH format); VideoDownloadOption.cs must handle downloading and muxing separate video/audio tracks, not single files.
• Metadata Tagging (ID3, Vorbis Comments) — MediaTagInjector.cs writes metadata to downloaded files; understanding ID3v2 (MP3), Vorbis comments (OGG), and MP4 atom structures is needed for correct metadata embedding.
• Value Converters & Data Binding — Converters/ directory contains IValueConverter implementations (EnumDisplayNameConverter, VideoQualityPreferenceToStringConverter) that transform data for UI display; understanding Avalonia's binding system and converter lifecycle is needed for UI work.
• File System Path Handling & Templating — FileNameTemplate.cs must safely construct file paths from user input with placeholders; must handle OS path separators, invalid characters, and character encoding across Windows/Linux/macOS.

• Tyrrrz/YoutubeExplode — Direct dependency and core library—YoutubeDownloader wraps this reverse-engineered YouTube API client; understanding it is essential for debugging download failures.
• yt-dlp/yt-dlp — Competing open-source YouTube downloader written in Python; different architecture (single CLI tool vs. GUI app) but solves identical problem; useful for feature comparison and cross-validation.
• Tyrrrz/CliFx — Same author's CLI framework library; YoutubeDownloader's UI uses similar patterns (DialogManager, ViewManager) but a CLI alternative could reuse Core logic.
• AvaloniaUI/Avalonia — UI framework underlying the entire YoutubeDownloader GUI; knowledge of Avalonia XAML, binding, and value converters is required to modify UI.
• AngleSharp/AngleSharp — Likely HTML parsing dependency (not visible in file list but common in reverse-engineering projects); YoutubeExplode may use it for parsing YouTube pages.

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 unit tests for VideoDownloader.cs core downloading logic

The YoutubeDownloader.Core/Downloading/VideoDownloader.cs file appears to be a critical component handling the main download orchestration, but there are no visible test files in the repo structure. Adding comprehensive unit tests would improve code reliability, catch regressions, and serve as documentation for how the downloader handles edge cases like invalid URLs, network failures, and format selection.

• [ ] Create YoutubeDownloader.Core.Tests project (if not exists) with xUnit/NUnit setup
• [ ] Add tests for VideoDownloader.cs covering: successful downloads, invalid query handling, FFmpeg integration failures, and VideoDownloadPreference application
• [ ] Add tests for FileNameTemplate.cs to verify template variable substitution (title, author, date, etc.)
• [ ] Add tests for QueryResolver.cs covering different query types (video URLs, playlist URLs, search queries) against QueryResultKind enum values
• [ ] Integrate test execution into .github/workflows/main.yml CI pipeline

Add integration tests for MusicBrainz tagging pipeline in YoutubeDownloader.Core/Tagging/

The tagging system (MusicBrainzClient.cs, MediaTagInjector.cs, MusicBrainzRecording.cs) handles metadata enrichment but has no visible test coverage. This is particularly important because it involves external API calls and file I/O. Tests would validate that metadata is correctly fetched, parsed, and injected into downloaded media files without corrupting them.

• [ ] Create integration test class for MusicBrainzClient.cs with mocked HTTP responses to avoid external API dependency
• [ ] Add tests for MusicBrainzRecording.cs deserialization from API responses
• [ ] Add tests for MediaTagInjector.cs verifying correct ID3/metadata tag injection into media files
• [ ] Test error handling: graceful degradation when MusicBrainz API is unreachable or returns no results
• [ ] Add fixtures with sample media files and expected metadata outputs

Add unit tests for Localization system and converters in YoutubeDownloader/

The project supports 6 languages (English, Chinese, French, German, Spanish, Ukrainian) with LocalizationManager and multiple converter classes (EnumDisplayNameConverter, MarkdownToInlinesConverter, etc.). Without tests, adding new localizations or modifying converters risks breaking translations or UI rendering. Tests would ensure consistency across all supported languages and converter logic.

• [ ] Create tests for LocalizationManager.cs verifying language switching and fallback to English when keys are missing
• [ ] Add tests for each LocalizationManager.*.cs language file validating all keys are present and non-empty
• [ ] Add tests for converters: EnumDisplayNameConverter.cs, VideoQualityPreferenceToStringConverter.cs, and MarkdownToInlinesConverter.cs with various input values
• [ ] Test that all 6 language files have parity in key counts to catch incomplete translations
• [ ] Add CI check to ensure no language files are missing keys present in English

• Add unit tests for FileNameTemplate.cs placeholder expansion—currently no visible test files; cover edge cases like missing metadata, special characters, and extremely long titles.
• Implement FFmpeg version detection and user guidance in FFmpeg.cs—currently no visible version check; add a startup validation that warns users if FFmpeg is missing or outdated, with link to install instructions.
• Expand QueryResolver.cs to handle YouTube Shorts URLs (youtube.com/shorts/ID)—likely not yet supported; add QueryResultKind.Short and route to single-video download pipeline with duration constraints.

The codebase demonstrates reasonable security awareness with features like settings encryption and external API integration. However, several medium-severity risks exist around command injection in FFmpeg integration, file path validation, and external API handling. The main concerns are: (1) potential unsafe

• Medium · Potential Command Injection in FFmpeg Integration — YoutubeDownloader.Core/Downloading/FFmpeg.cs. The FFmpeg.cs file likely constructs command-line arguments for external process execution. Without proper input validation and sanitization, there's a risk of command injection if user-controlled data (video titles, file names) is passed directly to FFmpeg arguments. Fix: Use Process.StartInfo with ArgumentList property instead of constructing shell commands as strings. Properly escape and validate all user inputs before passing to FFmpeg. Consider using a library that provides safe FFmpeg integration.
• Medium · Unsafe File Name Template Processing — YoutubeDownloader.Core/Downloading/FileNameTemplate.cs. The FileNameTemplate.cs processes user-provided templates for file naming. If the template resolution doesn't properly sanitize special characters or path traversal sequences, it could lead to directory traversal attacks or invalid file creation. Fix: Implement strict validation of file names. Remove or encode path separator characters, null bytes, and other OS-specific dangerous characters. Use Path.GetFileName() or similar safe methods. Validate against directory traversal patterns like '../'.
• Medium · Unvalidated External HTTP Requests — YoutubeDownloader.Core/Utils/Http.cs, YoutubeDownloader.Core/Tagging/MusicBrainzClient.cs. The Http.cs utility and MusicBrainzClient.cs make external HTTP requests without apparent HTTPS enforcement or certificate pinning. Additionally, MusicBrainzClient API responses are deserialized without visible schema validation. Fix: Enforce HTTPS-only connections. Implement certificate pinning for critical external services. Validate and sanitize all external API responses before deserialization. Use strict JSON schema validation.
• Medium · Encrypted Settings May Have Weak Key Management — YoutubeDownloader/Services/SettingsService.AuthCookiesEncryptionConverter.cs. The SettingsService.AuthCookiesEncryptionConverter.cs encrypts authentication cookies, but the key derivation method and storage location are not visible. If encryption uses a weak or hardcoded key, or stores keys insecurely, authentication credentials could be compromised. Fix: Use DPAPI (Data Protection API) on Windows or equivalent OS-level security APIs. Never hardcode encryption keys. Use proper key derivation functions (PBKDF2, bcrypt). Store sensitive data in secure system locations. Consider using authenticated encryption (AES-GCM).
• Low · Potential Markdown XSS in MarkdownToInlinesConverter — YoutubeDownloader/Converters/MarkdownToInlinesConverter.cs. The MarkdownToInlinesConverter.cs processes markdown content that may originate from YouTube metadata. If not properly sanitized before rendering, malicious markdown could potentially execute client-side code in the Avalonia UI context. Fix: Use a well-maintained markdown parser with built-in XSS protections. Implement strict allowlisting of markdown features. Sanitize any HTML output. Consider using libraries like Markdig with security-focused configuration.
• Low · Missing HTTPS Enforcement in Update Service — YoutubeDownloader/Services/UpdateService.cs. The UpdateService.cs checks for application updates. If update checks don't enforce HTTPS, attackers could perform MITM attacks to distribute malicious application versions. Fix: Enforce HTTPS-only for all update checks. Implement digital signature verification of downloaded updates. Use certificate pinning for the update server. Validate update manifest integrity and authenticity.
• Low · Process Execution Permissions Not Verified — YoutubeDownloader/Utils/NativeMethods.cs. NativeMethods.cs likely contains P/Invoke declarations for native Windows APIs. Improper usage could lead to privilege escalation or unauthorized system access. Fix: Minimize use of P/Invoke and native method calls. Apply principle of least privilege. Verify all native API calls are necessary and properly access-controlled. Document security implications of each native call.

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.