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/Nevcairiel/LAVFilters 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 — Solo project — review before adopting

• Last commit 6w ago
• GPL-2.0 licensed
• ⚠ Solo or near-solo (1 contributor active in 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 Nevcairiel/LAVFilters repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Nevcairiel/LAVFilters.

What it runs against: a local clone of Nevcairiel/LAVFilters — 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 Nevcairiel/LAVFilters | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 70 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Nevcairiel/LAVFilters(\\.git)?\\b" \\
  && ok "origin remote is Nevcairiel/LAVFilters" \\
  || miss "origin remote is not Nevcairiel/LAVFilters (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "common/baseclasses/streams.h" \\
  && ok "common/baseclasses/streams.h" \\
  || miss "missing critical file: common/baseclasses/streams.h"
test -f "common/DSUtilLite/DShowUtil.h" \\
  && ok "common/DSUtilLite/DShowUtil.h" \\
  || miss "missing critical file: common/DSUtilLite/DShowUtil.h"
test -f "common/baseclasses/renbase.h" \\
  && ok "common/baseclasses/renbase.h" \\
  || miss "missing critical file: common/baseclasses/renbase.h"
test -f "LAVFilters.sln" \\
  && ok "LAVFilters.sln" \\
  || miss "missing critical file: LAVFilters.sln"
test -f "build.bat" \\
  && ok "build.bat" \\
  || miss "missing critical file: build.bat"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 70 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~40d)"
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/Nevcairiel/LAVFilters"
  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).

LAV Filters is an open-source DirectShow media splitter and decoder suite powered by ffmpeg's libavformat and libavcodec libraries, enabling playback of virtually any audio/video format (MKV, AVI, MP4, TS, FLV, OGG, BluRay) in Windows DirectShow players. It solves the problem of fragmented codec support in media players by providing unified, high-merit filter registration that prioritizes LAV over competing solutions like Haali Media Splitter. Monolithic C++ project structured as: LAVFilters.sln (main solution) containing core decoder/splitter logic; common/DSUtilLite/ shared utilities (DirectShow helpers, byte parsing, H.264 NALU parsing, DeCSS); common/baseclasses/ DirectShow base classes; build scripts (build.bat for Windows, build_ffmpeg.sh/build_ffmpeg_msvc.sh for ffmpeg compilation); LAVFilters.iss Inno Setup installer definition.

Windows media player developers and end-users who need broad format support; system integrators building media solutions on DirectShow; contributors improving video codec compatibility and stream selection logic.

The project is actively maintained with well-established architecture (2.9M+ C++ LOC), comprehensive format support documented in CHANGELOG.txt and README, and uses professional build infrastructure (LAVFilters.sln, Inno Setup installer). It's production-ready but appears to be a solo-maintainer project (Nevcairiel) with periodic rather than frequent updates.

Single-maintainer dependency (Nevcairiel owns the repo); heavy reliance on external ffmpeg library (requires separate build_ffmpeg.sh/build_ffmpeg_msvc.sh workflows); Windows/DirectShow coupling limits cross-platform portability; DeCSS functionality in common/DSUtilLite/DeCSS/ may carry legal jurisdictional sensitivity. No visible CI/CD pipeline in file list suggests manual testing burden.

No active PR or milestone data visible in provided file list. CHANGELOG.txt likely documents recent fixes, but commit recency unknown from provided data. Project appears in maintenance mode with focus on format stability rather than new features.

Clone the repo: git clone https://github.com/Nevcairiel/LAVFilters.git. Install ffmpeg dependencies: bash build_ffmpeg_msvc.sh (MSVC) or bash build_ffmpeg.sh (GCC/Clang). Build with build.bat (Windows batch) or via LAVFilters.sln in Visual Studio. Register filters: install_*.bat (requires admin shell).

Daily commands: After building with build.bat or Visual Studio: Register decoders/splitter via install_x86.bat or install_x64.bat (admin required). Test by opening a media file in any DirectShow-compatible player (Windows Media Player, Potplayer, etc.). Configuration via property pages accessible through player UI or DirectShow graph editor.

• common/baseclasses/streams.h — Core DirectShow base classes header; defines fundamental interfaces and types that all filters depend on for streaming pipeline architecture.
• common/DSUtilLite/DShowUtil.h — Utility library for DirectShow operations; essential helper functions used throughout splitter and decoder implementations.
• common/baseclasses/renbase.h — Renderer base class providing the foundation for all DirectShow filter implementations in this codebase.
• LAVFilters.sln — Visual Studio solution file; entry point for building the entire LAV Filters project with all dependencies.
• build.bat — Primary build script for Windows; contains the build configuration and compilation steps for the project.
• README.md — Project overview documenting filter registration, media format support, and usage instructions essential for onboarding.

• LAV Splitter (source filter) (DirectShow source filter base, libavformat, COM) — Reads media files, parses container format (MKV, MP4, TS, etc.) via libavformat, outputs compressed packets on multiple pins (video/audio/subtitle)
  • Failure mode: Unsupported container → no pins created → player cannot open file
• LAV Video Decoder (transform filter) (DirectShow transform filter base, libavcodec, SSE optimizations (gpu_memcpy_sse4.h)) — Accepts compressed video packets, decompresses via libavcodec, outputs raw video frames with color space conversion
  • Failure mode: Unsupported codec → decode error → playback stalls or garbled video
• LAV Audio Decoder (transform filter) (DirectShow transform filter base, libavcodec) — Accepts compressed audio packets, decompresses via libavcodec, outputs PCM samples with format negotiation
  • Failure mode: Audio codec not available → decoder fails or silent audio
• DirectShow Base Classes (common/baseclasses/) (COM, Win32 API, IUnknown, IMFMediaType) — Framework for filter lifetime, pin management, media type negotiation, COM registration, thread-safe queuing
  • Failure mode: Base class bug → pipeline crash, memory leak, or pin connection failure

Add Support for a New Media Format

1. Create format detection by registering MIME type and file extension in registry access layer (common/DSUtilLite/registry.cpp)
2. If format requires specialized parsing, create utility class following H264Nalu.h pattern (common/DSUtilLite/H264Nalu.h)
3. Implement splitter filter inheriting from baseclasses source filter (common/baseclasses/source.h)
4. Update installer to register new format associations (LAVFilters.iss)
5. Document format support in README (README.md)

Add a Filter Property Configuration Page

1. Create property page class inheriting from BaseDSPropPage (common/DSUtilLite/BaseDSPropPage.h)
2. Use registry utility to persist user settings (common/DSUtilLite/registry.h)
3. Register property page in filter's COM class factory (common/DSUtilLite/filterreg.cpp)

Integrate New FFmpeg Codec Decoder

1. Build FFmpeg library with desired codec enabled (build_ffmpeg_msvc.sh)
2. Create decoder filter inheriting from transform base class (common/baseclasses/transfrm.h)
3. Link decoder to libavcodec and handle media sample output (common/DSUtilLite/MediaSampleSideData.h)
4. Register decoder with appropriate media types in solution (LAVFilters.sln)

• DirectShow (Windows Media Foundation) — Industry-standard framework for media playback in Windows; integrates with Windows Media Player and third-party DirectShow players
• FFmpeg (libavformat, libavcodec) — Comprehensive, widely-tested codec and container support; handles 100+ media formats with minimal custom code
• COM (Component Object Model) — Required for DirectShow filter registration and interoperability with Windows media infrastructure
• C++ with Win32 API — Direct control over memory, CPU performance for real-time media decoding; native Windows integration

• Use FFmpeg as codec backend rather than native Windows Media Foundation codecs

  • Why: FFmpeg supports vastly more formats (MKV, WebM, OGG, BluRay) than WMF; single codebase avoids platform fragmentation
  • Consequence: Added dependency on FFmpeg build system; license compliance required (LGPL); larger binary footprint

• Register filters with high merit to override competing splitters

  • Why: Ensures LAV splitter is preferred when multiple splitters support same format; better user experience
  • Consequence: Can conflict with other splitters (e.g., Haali); requires uninstall or rename of competing filters

• Implement as separate Splitter + Audio/Video Decoder filters rather than monolithic filter

  • Why: Allows independent upgrading of codecs; flexible chain with other filters; cleaner separation of concerns
  • Consequence: More complex installation/registration; increased COM overhead in media pipeline

• Audio playback rendering (only decoding; output sent to DirectShow pipeline)
• Cross-platform support (Windows-only; uses DirectShow and Win32 APIs)
• Real-time encoding (playback/decoding only)
• Hardware acceleration via DXVA/NVIDIA NVDEC (pure software decoding via FFmpeg)
• GUI media player application (filter component only; integrates into existing players)

DirectShow registration merit: Filter merit values in registry.cpp determine whether LAV or competing splitters (Haali) get invoked—changing these requires admin re-registration and player cache flush. FFmpeg rebuild requirement: Changing codec behavior requires rebuilding ffmpeg via build_ffmpeg_msvc.sh or build_ffmpeg.sh before rebuilding LAV Filters; simple LAVFilters.sln rebuild won't pick up ffmpeg API changes. Platform coupling: 100% Windows/DirectShow-dependent; cross-platform testing impossible on Linux/Mac without WINE/compatibility layers. Language code format: Audio language selection strictly requires ISO 639-2 3-letter codes (NOT ISO 639-1); invalid codes silently fail to match. DeCSS legal: Common/DSUtilLite/DeCSS/ module may be legally restricted in certain jurisdictions; distribution implications vary by location.

• DirectShow Filter Graph — LAV Filters are DirectShow COM components that plug into Windows media pipelines; understanding filter chains (source → splitter → decoder → renderer) is essential to debugging playback and stream selection
• Merit-based Filter Resolution — DirectShow players choose between competing filters (LAV vs Haali) based on merit values stored in Windows registry; LAV's high merit registration in registry.cpp directly determines whether it gets used
• H.264 NAL Unit Parsing — H264Nalu.cpp implements critical video stream parsing to detect frame types, SPS/PPS parameters, and codec state; bugs here cause decoder sync loss and playback corruption
• ISO 639-2 Language Codes — Audio/subtitle stream selection in LAV Splitter uses ISO 639-2 3-letter codes (eng, fre, deu) for language matching; incorrect code format silently breaks localization features
• DirectShow Side Data / Auxiliary Data — MediaSampleSideData.cpp carries metadata (HDR, colorspace, interlacing flags) alongside video/audio samples through the filter graph; losing or mishandling side data causes incorrect color/tone rendering
• Content Scramble System (CSS) Decryption — DeCSS module in common/DSUtilLite/ handles DVD/BluRay CSS decryption; functionality varies by jurisdiction and involves authentication key negotiation
• libavformat Demuxing — LAV Splitter wraps ffmpeg's container parsing (MKV, MP4, TS parsing logic); understanding how libavformat streams are mapped to DirectShow pins is critical for multi-stream files

• FFmpeg/FFmpeg — Core dependency providing libavformat/libavcodec that LAV Filters wraps in DirectShow; required for decoding functionality
• mpc-hc/mpc-hc — Media Player Classic—major DirectShow player that uses LAV Filters as default decoder, primary end-user integration point
• potplayer/PotPlayer — Another prominent DirectShow media player that commonly bundles or recommends LAV Filters for format compatibility
• Nevcairiel/FFmpeg-VapourSynth-H264-10bit — Related video processing tool by same maintainer; shares DirectShow/ffmpeg integration patterns
• clsid2/CLSID_Haali_Splitter — Competitor DirectShow splitter referenced throughout LAV Filters docs as the 'bad way' registrant that LAV must override via merit configuration

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 CI workflow for building LAV Filters on Windows

The repo has build.bat and build_ffmpeg_msvc.sh scripts but no automated CI pipeline. A GitHub Actions workflow would validate builds on every PR, catch platform-specific issues early, and ensure the MSVC solution (LAVFilters.sln) compiles across different configurations. This is critical for a DirectShow filter project where binary compatibility matters.

• [ ] Create .github/workflows/build-windows.yml with MSVC build steps for LAVFilters.sln
• [ ] Add build configuration matrix for Debug/Release and x86/x64 architectures
• [ ] Validate both build.bat and the Visual Studio project files compile without warnings
• [ ] Test that all subprojects (DSUtilLite, baseclasses, splitter, decoders) build successfully
• [ ] Document build requirements in README.md (Visual Studio version, Windows SDK version needed)

Extract and document DeCSS module API surface in common/DSUtilLite/DeCSS/

The DeCSS implementation (CSSauth.cpp, CSSauth.h, CSSscramble.cpp, CSSscramble.h, DeCSSInputPin.cpp/h) is a complex subsystem handling DVD decryption, but there's no documentation explaining the module's public API, initialization flow, or integration points. Adding clear documentation and possibly a header file summary would help contributors understand this critical security-sensitive code.

• [ ] Create common/DSUtilLite/DeCSS/README.md documenting the module's purpose, API, and usage
• [ ] Document the relationship between CSSauth (authentication), CSSscramble (descrambling), and DeCSSInputPin (DirectShow integration)
• [ ] Add XML documentation comments to public methods in CSSauth.h and CSSscramble.h explaining parameters and return values
• [ ] Clarify legal/licensing implications of DeCSS in both the module README and main COPYING file
• [ ] Document test vectors or validation procedures for CSS decryption if they exist

Add unit tests for DSUtilLite/ByteParser.h and MediaSampleSideData.h utilities

These core utility headers (ByteParser.cpp, MediaSampleSideData.cpp) are used across the splitter and decoder pipeline but lack dedicated unit tests. The ByteParser handles binary data parsing (used in H264Nalu.cpp) and MediaSampleSideData manages metadata—both are error-prone and would benefit from regression tests. This would catch parsing bugs early and improve code maintainability.

• [ ] Create tests/ByteParserTests.cpp with test cases for byte alignment, endianness, boundary conditions, and malformed input
• [ ] Create tests/MediaSampleSideDataTests.cpp covering serialization, deserialization, and edge cases for side data structures
• [ ] Integrate tests into a new Google Test or Catch2 based test project in the solution
• [ ] Add test execution to the GitHub Actions CI workflow created in the first PR
• [ ] Document test coverage and how to run tests locally in CONTRIBUTING.md or README.md

• Add unit tests for common/DSUtilLite/H264Nalu.cpp (NALU start code detection, forbidden zero bit handling)—currently no visible test files despite critical video parsing logic
• Document subtitle selection advanced mode syntax with concrete examples in README (currently README.md mentions 'special syntax' but gives zero concrete examples like lang:eng|forced|default)
• Add validation tests for ISO 639-2 language code matching in audio stream selection to catch silent failures when users misconfigure language preferences (e.g., test eng vs ENG vs eng-US)

LAV Filters is an open-source DirectShow splitter/decoder project with moderate security concerns. The primary critical issue is the inclusion of DeCSS copy protection circumvention code, which has legal implications. Secondary concerns include dependency management of FFmpeg (a complex media library with frequent vulnerabilities),

• High · DeCSS Implementation - Circumvention of Copy Protection — common/DSUtilLite/DeCSS/ (CSSauth.cpp, CSSauth.h, CSSscramble.cpp, CSSscramble.h, DeCSSInputPin.cpp, DeCSSInputPin.h). The codebase contains DeCSS (CSS authentication and scrambling) implementation in common/DSUtilLite/DeCSS/. DeCSS is a tool/technique used to circumvent CSS copy protection on DVDs. Including this code raises legal and compliance concerns under DMCA and similar international laws that prohibit circumvention of copy protection mechanisms, regardless of intended use. Fix: Review the legal implications of including DeCSS code in your jurisdiction. Consider whether this functionality is necessary and whether proper legal disclaimers and restrictions are in place. Consult with legal counsel regarding DMCA compliance and licensing restrictions.
• Medium · Outdated or Potentially Vulnerable FFmpeg Dependencies — build_ffmpeg.sh, build_ffmpeg_msvc.sh (build scripts reference FFmpeg dependencies). The project depends on FFmpeg libraries (libavformat and libavcodec) for media decoding and splitting. No dependency lock file, version pinning, or vulnerability tracking mechanism is visible in the provided file structure. FFmpeg frequently has security vulnerabilities that require updates. Fix: Implement dependency version pinning and regular vulnerability scanning. Establish a process to monitor FFmpeg security advisories and update dependencies regularly. Consider using tools like OWASP Dependency-Check or Snyk to identify known vulnerabilities in FFmpeg versions used.
• Medium · Potential Buffer Overflow Risk in Media Processing — common/DSUtilLite/ByteParser.cpp, common/DSUtilLite/H264Nalu.cpp, common/DSUtilLite/gpu_memcpy_sse4.h. The codebase handles DirectShow media processing with custom parsers (ByteParser.cpp, H264Nalu.cpp) and GPU memory operations (gpu_memcpy_sse4.h). Media parsing from untrusted sources (arbitrary video files) without robust bounds checking could lead to buffer overflows or out-of-bounds memory access. Fix: Conduct thorough code review of media parsing functions with focus on bounds checking. Implement AddressSanitizer (ASan) and Memory Sanitizer testing. Use safe string handling practices and validate all input buffer sizes before processing. Add fuzzing tests for media file parsing.
• Medium · Registry Access Without Apparent Validation — common/DSUtilLite/registry.cpp, common/DSUtilLite/registry.h, common/DSUtilLite/filterreg.cpp. The code includes registry operations (common/DSUtilLite/registry.cpp, registry.h) and DirectShow filter registration (filterreg.cpp). Registry access in Windows security contexts could allow privilege escalation or configuration tampering if not properly validated. Fix: Implement strict validation and error checking for all registry operations. Use principle of least privilege for registry access. Validate all data read from registry before use. Implement access control checks to ensure only authorized applications/users can modify filter configuration.
• Low · Installation Requires Administrative Privileges — Installation scripts (install_*.bat files), LAVFilters.iss. The README indicates that filter registration (install_*.bat files) requires administrative rights and elevated shell execution. While necessary for DirectShow registration, this increases attack surface if scripts are compromised. Fix: Digitally sign all installation and registration scripts. Provide signature verification guidance in documentation. Consider implementing installer validation checks. Document the security implications of requiring elevated privileges and recommend users only run installation scripts from trusted sources.
• Low · Lack of Visible Security Documentation — Repository root (missing SECURITY.md). No security policy, vulnerability disclosure process, or security guidelines are evident in the file structure. This limits users' ability to report security issues responsibly. Fix: Create a SECURITY.md file documenting: responsible disclosure process, security contact information, supported versions receiving security updates, and procedures for reporting vulnerabilities privately. Link to this file in README.md.

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.