# Windows playback source and library replacement

HL Player uses libmpv as a dynamically loaded library. The Windows build uses
mpv with GPL code disabled and FFmpeg with GPL and nonfree components disabled.
The LGPL libraries within this DLL can be rebuilt together from the accompanying
original sources. This is separate from Android's runtime and from the
`media_tools` FFmpeg/FFprobe component.

`corresponding-source.zip` contains the original source archives, SHA-256 lock,
build recipe, configuration evidence, license texts, and local-change record.
`manifest.json` identifies the exact shipped DLL and source archive. The LGPL
license permits modifying these libraries and reverse engineering HL Player for
debugging such modifications. The application terms do not restrict those rights.
There is no application-time signature/hash restriction on a replacement libmpv.
Packaging checks protect the identity of the distributed artifact only.

## Rebuild

Extract the source ZIP to a directory you own. The build orchestration is MIT
licensed; the FFmpeg patch/application module retains LGPL-2.1-or-later.
Original components retain the licenses included with their source.

Reference environment: Windows x64, Python 3.12, LLVM-MinGW 20260616 UCRT
(Clang 22.1.8), CMake 3.31.6, Ninja 1.12.1, Meson 1.9.1, Jinja2 3.1.6,
MarkupSafe 3.0.3; MSYS2 bash 5.3.015, make 4.4.1, nasm 2.16.03, pkgconf 2.5.1.
Tool versions and download identities are recorded in `recipe/toolchain.lock.json`.
These tools are used to build the library; they are not bundled app runtimes.

Install the Python build tools into an isolated directory:

```powershell
python -m pip install --target C:\hlp-build\python-tools meson==1.9.1 Jinja2==3.1.6 MarkupSafe==3.0.3
```

Extract the pinned LLVM-MinGW ZIP, verify its SHA-256 against the toolchain lock,
and provide the CMake, Ninja and MSYS2 paths on your machine. From the source ZIP:

```powershell
python recipe/prepare_sources.py --offline --work C:\hlp-build\work --archives .\archives
python recipe/build.py --work C:\hlp-build\work `
  --llvm C:\hlp-build\llvm-mingw-20260616-ucrt-x86_64 `
  --python-tools C:\hlp-build\python-tools `
  --cmake C:\hlp-build\cmake\bin\cmake.exe `
  --ninja C:\hlp-build\ninja\ninja.exe --msys C:\msys64
```

The recipe applies the documented FFmpeg UTF-16 lookahead correction in
`recipe/apply_patches.py`; `ffmpeg-utf16-lookahead.patch` and `changes.txt`
record the LGPL source modification. It preserves UTF-8 continuation bytes
when a UTF-16 subtitle line begins with a non-ASCII character.

The result is `work/prefix/bin/libmpv-2.dll`. The recipe preserves the libmpv
client/render ABI, Windows audio, OpenGL/ANGLE interop, subtitle rendering and
encoding conversion, AV1 software decoding, and HTTP/TLS network support.
It does not build the mpv command-line application, GPL codecs, Lua/JavaScript
scripting, archive/disc navigation, or Vulkan video output. HL Player uses the
libmpv render API with ANGLE's Direct3D backend, with its software rendering
fallback. These optional mpv CLI capabilities are not HL Player's library backup
or ZIP import/export implementation.

For modifications, edit the extracted `work/sources` files and rerun the affected
stages with `--stages`, in dependency order, ending with `mpv`. Do not rerun the
source preparation step over modified sources. For example, after modifying
mpv alone, add `--stages mpv` to the build command. A fresh complete build from
the preserved inputs is supported; bit-for-bit output across different tool
versions and filesystem paths is not promised.

## Replace outside the Store installation directory

Do not change the protected `WindowsApps` installation or disable package trust.
Close HL Player and make a separate writable copy of the **complete** application
directory, including `data`, the native DLLs, `playback`, and `media_tools`.
The installed location can be read from Windows' `Get-AppxPackage` result for
the exact HL Player package identity. An unpacked MSIX/portable distribution
containing the same application files is another suitable starting point.

Replace only `libmpv-2.dll` in that writable copy with your rebuilt Windows x64
library. Keep the same libmpv client and render API major version (2), exports,
and compatible behavior. If your build uses additional DLLs, keep their matching
x64 versions beside it. Run `hlplayer.exe` from that complete copy. The copy is
an unpackaged application and is not updated or signed by Microsoft Store.
It uses the existing Windows user data locations; back up settings before
testing changes. An unpackaged launch may register the normal `hlplayer` URI
handler to that copy. Store application files remain intact.

The provided command can create the copy without launching it:

```powershell
.\recipe\copy_for_library_replacement.ps1 -InstalledDirectory C:\path\to\installed\HLPlayer `
  -ReplacementDll C:\hlp-build\work\prefix\bin\libmpv-2.dll `
  -Destination C:\hlp-build\modified-player
```

Only rebuild/replace libraries obtained from sources you trust. The library
executes with the same permissions as the application. Modified versions are
provided under their applicable upstream licenses, without HL Player support
or warranty. Original source requests can also be sent to `support@hlplayer.app`.

## 한국어 안내

정확한 Windows 재생 라이브러리 소스·빌드 방법·라이선스는 이 폴더의
`corresponding-source.zip`에 들어 있습니다. LGPL 라이브러리를 수정하고, 수정 사항을
디버깅하기 위해 앱을 역공학할 권리를 제한하지 않습니다. WindowsApps 안의 설치
파일을 수정하는 대신 전체 앱을 쓰기 가능한 별도 폴더로 복사한 뒤 호환되는 x64
`libmpv-2.dll`로 교체할 수 있습니다. 앱 실행 시 DLL 서명이나 배포 해시로 교체를
차단하지 않습니다. 수정판은 Store 업데이트 대상이 아니며 기존 사용자 데이터를
사용할 수 있으므로 시험 전에 설정을 백업하세요. 원본 미디어를 삭제할 필요는 없습니다.