# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

**One-time setup:**
```bash
bash scripts/dev/setup_sdk_dev.sh
```

**Build demos:**
```bash
bash scripts/dev/build_demo.sh all    # both ObjC and Swift demos
bash scripts/dev/build_demo.sh objc
bash scripts/dev/build_demo.sh swift
```

**Tests:** Run via Xcode or `xcodebuild test` — no standalone test script exists.

**IDE:** Open `QGVAPlayerDev.xcworkspace` to work on SDK + demos together.

## Architecture

QGVAPlayer is a high-performance iOS video animation player (iOS 12+) using H.264 hardware decoding and Metal GPU rendering. It plays VAP-format MP4s with transparent channel support, used for live-streaming special effects.

**Data flow:** MP4 file → `LNMP4Parser` (reads VAP boxes) → `LNAnimatedImageDecodeThreadPool` (multi-threaded frame decode) → `LNHWDMetalCoreRenderer` (YUV→RGB, Metal shaders) → `LNVAPPlayerView` (UIView display)

**Key source locations (all under `QGVAPlayer/QGVAPlayer/LNSwift/`):**

| Directory | Purpose |
|-----------|---------|
| `Core/` | Playback engine (`LNControllers.swift`, `LNVAPFacade.swift`) |
| `View/` | `LNVAPPlayerView` (primary API), `LNVAPWrapView` |
| `Render/` | Metal renderer; OpenGL fallback via `renderByOpenGL` flag |
| `Parser/` | `LNMP4Parser` — reads MP4 boxes including custom `vapc` metadata |
| `Model/` | Playback types and data models |
| `Bridges/` | ObjC compatibility shims (`LNLegacyMappings.swift`) |

**Public API entry point:** `LNVAPPlayerView.lnPlay(filePath:repeatCount:)` — any UIView can host this. Delegates: `LNVAPPlaybackDelegate` (Swift) and `LNVAPLegacyPlaybackDelegate` (ObjC).

**Rendering:** Metal (`LNHWDMetalCoreRenderer`) is default on iOS 13+; shaders live in `QGVAPlayer/QGVAPlayer/Shaders/QGHWDShaders.metal`. Alpha blend modes (left/right/top/bottom) are configured via `vapc` MP4 box metadata.