video-v1/vav2/CLAUDE.md

Vav2Player - AV1 Video Player 개발 프로젝트

⚠️ 코딩 규칙 (CRITICAL)

📝 주석 및 코드 스타일

• 모든 주석은 영어로 작성 (.h, .cpp, .java 등 모든 소스 파일)
• 이모지 사용 금지 (주석, 문자열, 로그 메시지)
• 테스트 코드는 별도 프로젝트에 작성 (vav2/platforms/*/tests/ 디렉토리)

🛠️ 개발 도구

• Windows Python 실행: py 사용 (NOT python)

  py script.py          # 올바름
  python script.py      # 잘못됨 (PATH 문제 가능)
  

---

🎯 현재 프로젝트 상태 (2025-10-12)

✅ 완료된 주요 기능

Windows 플랫폼

• VavCore C API: 28개 vavcore_* 함수 완전 구현
• 하드웨어 가속: NVIDIA NVDEC, Intel VPL, AMD AMF 지원
• VavCore.Godot Extension: Zero-Copy GPU Pipeline + CPU Fallback
• Vav2Player GUI: WinUI3 애플리케이션 (VideoPlayerControl2)
• D3D12 렌더링: YUV→RGB GPU 쉐이더, AspectFit 스케일링
• CUDA Surface Objects: 90도 회전 문제 완전 해결

Android 플랫폼

• Vulkan AV1 Player: 네이티브 Vulkan 1.1 렌더링
• MediaCodec 하드웨어 가속: 키워드 기반 디코더 선택 (Samsung, Qualcomm, MediaTek 지원)
• VavCore Android JNI: C API 28개 함수 NDK 연동
• Surface Lifecycle: VkDevice 유지하며 Surface 재생성 (표준 Android 패턴)
• Intent Auto-play: 파일 경로 지정 시 자동 재생 지원
• Google Play 호환: Android 15+ 16KB 페이지 크기 지원

📊 성능 지표

• 4K AV1 디코딩: Windows 9-15ms (NVDEC), Android MediaCodec 최적화
• 크로스 플랫폼: Windows DLL + Android JNI 통일 API
• GPU 렌더링: D3D12 (Windows) + Vulkan 1.1 (Android)

---

📁 프로젝트 구조

D:\Project\video-av1\
├── vav2/
│   └── platforms/
│       ├── windows/
│       │   ├── vavcore/              # VavCore 라이브러리 (C/C++ DLL)
│       │   ├── godot-plugin/         # Godot 4.4.1 Extension
│       │   ├── applications/
│       │   │   └── vav2player/       # WinUI3 GUI 앱
│       │   └── tests/                # 모든 Windows 테스트
│       └── android/
│           ├── vavcore/              # Android VavCore (CMake)
│           │   ├── lib/
│           │   │   ├── android-arm64-v8a/
│           │   │   └── android-armeabi-v7a/
│           │   └── src -> ../../windows/vavcore/src  # 공유 소스
│           └── applications/
│               └── vav2player/       # Vulkan AV1 Player 앱
├── include/                          # 공통 헤더 (libwebm, dav1d, amf, libvpl)
└── lib/                              # 플랫폼별 라이브러리
    ├── windows-x64/
    ├── android-arm64/
    └── android-arm32/

---

🔨 빌드 가이드

Windows 플랫폼

# 전체 빌드
cd "D:\Project\video-av1\vav2\platforms\windows"
./build-all.bat

# GUI 애플리케이션 (Visual Studio 권장)
cd "applications\vav2player"
"C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" Vav2Player.sln //p:Configuration=Debug //p:Platform=x64 //v:minimal

Android 플랫폼

# VavCore 빌드
cd "D:\Project\video-av1\vav2\platforms\android\vavcore"
cmd /c "build_vavcore_android.bat arm64"  # ARM64
cmd /c "build_vavcore_android.bat arm32"  # ARM32

# Android 앱 빌드 및 설치
cd "../applications/vav2player"
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

Android NDK 환경 설정

export ANDROID_NDK_HOME=/path/to/android-ndk-r25
# 또는
export ANDROID_NDK_ROOT=/path/to/android-ndk-r25

---

🧪 테스트 가이드

Windows 테스트

# 유닛 테스트 (Visual Studio Test Explorer 권장)
cd "platforms\windows\tests\unit-tests"
MSBuild Vav2UnitTest.vcxproj //p:Configuration=Debug //p:Platform=x64

# 헤드리스 테스트
cd "platforms\windows\tests\headless"
MSBuild Vav2PlayerHeadless.vcxproj //p:Configuration=Debug //p:Platform=x64
.\x64\Debug\Headless\Vav2PlayerHeadless.exe "test_video.webm"

Android 테스트

# Intent로 비디오 자동 재생
adb shell "am start -n com.vavcore.player/.MainActivity --es filepath '/sdcard/Download/output.webm'"

# ACTION_VIEW Intent
adb shell "am start -a android.intent.action.VIEW -d 'file:///sdcard/Download/output.webm' -t 'video/webm'"

# 로그 확인
adb logcat | grep -E "(VavCore|Vulkan|MainActivity)"

---

📋 핵심 아키텍처

데이터 플로우

[AV1 File] → [libwebm Parser] → [AV1 Packet Queue]
           → [Hardware Decoder (NVDEC/MediaCodec/VPL/AMF/dav1d)]
           → [YUV Frame] → [GPU Renderer (D3D12/Vulkan)] → [Display]

Windows 하드웨어 디코더 우선순위

NVDEC (NVIDIA) → VPL (Intel) → AMF (AMD) → dav1d (SW fallback)

Android MediaCodec 우선순위

exynos, sec (Samsung) → qcom, qti (Qualcomm) → mtk (MediaTek) → android, google (AOSP)

---

🎯 다음 단계 (향후 확장)

옵션 1: 추가 플랫폼

• iOS/macOS: Metal 기반 VavCore 구현
• 웹 플랫폼: WebAssembly 브라우저 플레이어

옵션 2: 기능 확장

• 오디오 지원: VavCore 오디오 디코딩 추가
• 네트워크 스트리밍: RTMP/HLS AV1 스트리밍

옵션 3: 게임 엔진 통합

• Unity 플러그인
• Unreal Engine 플러그인

---

📚 참고 문서

완료된 프로젝트

• Complete Projects Archive - 완료된 20개 미니 프로젝트
• Android Vulkan AV1 Player
• CUDA Surface Object Refactoring

설계 문서

• VavCore Godot Integration
• VavCore Library Design

---

🐛 주요 해결된 문제

NVDEC 90도 회전 문제 (2025-10-06)

• 원인: cudaExternalMemoryGetMappedBuffer()가 D3D12 tiled 텍스처를 linear buffer로 해석
• 해결: CUDA Surface Objects + surf2Dwrite() 커널 사용

Android Surface Lifecycle (2025-10-12)

• 원인: VkDevice 파괴 후 VavCore에 등록된 포인터 invalid
• 해결: DestroySurface/RecreateSurface 패턴으로 VkDevice 유지

VavCore-debug.dll 로드 실패 (2025-10-01)

• 원인: WinUI3 AppX 디렉토리에 DLL 복사 안 됨
• 해결: Visual Studio에서 빌드 (post-build event 정상 실행)

---

최종 업데이트: 2025-10-12 Claude Code로 생성됨