485 lines
17 KiB
Markdown
485 lines
17 KiB
Markdown
# MediaCodec Android Decoder 개선 분석
|
|
|
|
**작성일**: 2025-10-11 (Updated: 2025-10-11 19:30 KST)
|
|
**대상**: Android MediaCodec AV1 Decoder
|
|
**참고**: NVDEC DecodeToSurface() 스펙 변경사항 반영
|
|
**상태**: ✅ **Phase 1-2 구현 완료** (State Machine + DecodeToSurface 리팩토링)
|
|
|
|
---
|
|
|
|
## 📋 Executive Summary
|
|
|
|
NVDEC 개선 과정에서 `DecodeToSurface()` API 스펙이 크게 변경되었습니다. MediaCodec도 동일한 설계 원칙을 따라 개선이 필요합니다.
|
|
|
|
### 🎯 Implementation Status (2025-10-11)
|
|
|
|
✅ **Phase 1-2 Completed**: Core improvements implemented and ready for testing
|
|
- State Machine: READY → BUFFERING → DECODING → FLUSHING
|
|
- MediaCodec API-compliant DecodeToSurface() implementation
|
|
- Always calls ProcessOutputBuffer() regardless of buffering state
|
|
- Surface configured BEFORE input queueing (MediaCodec requirement)
|
|
- State-based return logic (false for PACKET_ACCEPTED/END_OF_STREAM)
|
|
|
|
⏳ **Phase 5 Pending**: Android platform testing required
|
|
|
|
**핵심 변경사항**:
|
|
1. **CUDA DPB 도입**: NVDEC은 내부 CUDA DPB를 통한 B-frame 리오더링 지원
|
|
2. **State Machine**: READY → BUFFERING → DECODING → FLUSHING 명확한 상태 관리
|
|
3. **False Return**: 프레임 미출력 시 `false` 반환 (VAVCORE_PACKET_ACCEPTED로 변환)
|
|
4. **PTS 기반 리오더링**: DisplayQueue를 통한 표시 순서 관리
|
|
|
|
---
|
|
|
|
## 🔍 1. 현재 MediaCodec 구현 상태
|
|
|
|
### 1.1 DecodeToSurface() 구현 (MediaCodecAV1Decoder.cpp:195-287)
|
|
|
|
```cpp
|
|
bool MediaCodecAV1Decoder::DecodeToSurface(const uint8_t* packet_data, size_t packet_size,
|
|
VavCoreSurfaceType target_type,
|
|
void* target_surface,
|
|
VideoFrame& output_frame) {
|
|
if (!m_initialized) {
|
|
LogError("Decoder not initialized");
|
|
return false;
|
|
}
|
|
|
|
if (target_type == VAVCORE_SURFACE_ANDROID_NATIVE_WINDOW) {
|
|
// Set output surface for hardware acceleration
|
|
ANativeWindow* native_surface = static_cast<ANativeWindow*>(target_surface);
|
|
if (native_surface && native_surface != m_surface) {
|
|
media_status_t status = AMediaCodec_setOutputSurface(m_codec, native_surface);
|
|
if (status != AMEDIA_OK) {
|
|
LogError("Failed to set output surface: " + std::to_string(status));
|
|
return false;
|
|
}
|
|
m_surface = native_surface;
|
|
}
|
|
|
|
// Process input buffer
|
|
if (!ProcessInputBuffer(packet_data, packet_size)) {
|
|
LogError("Failed to process input buffer for surface rendering");
|
|
return false;
|
|
}
|
|
|
|
// ❌ 문제: Output buffer dequeue 없이 즉시 리턴!
|
|
// Output will be rendered directly to surface
|
|
// No need to copy frame data
|
|
IncrementFramesDecoded();
|
|
return true; // ← 프레임 출력 여부와 무관하게 항상 true
|
|
}
|
|
// ... (OpenGL ES, Vulkan 경로 유사)
|
|
}
|
|
```
|
|
|
|
**문제점**:
|
|
- ❌ **Output buffer dequeue 누락**: `ProcessOutputBuffer()` 호출 없음
|
|
- ❌ **항상 true 반환**: 프레임 출력 여부 확인 없이 무조건 true 반환
|
|
- ❌ **State Machine 없음**: BUFFERING/DECODING 구분 없음
|
|
- ❌ **동기화 부족**: MediaCodec 비동기 처리 특성 무시
|
|
|
|
---
|
|
|
|
## 🎯 2. NVDEC DecodeToSurface() 설계 (참고 모델)
|
|
|
|
### 2.1 핵심 설계 원칙
|
|
|
|
```cpp
|
|
// NVDECAV1Decoder.cpp:381-613
|
|
bool NVDECAV1Decoder::DecodeToSurface(const uint8_t* packet_data, size_t packet_size,
|
|
VavCoreSurfaceType target_type,
|
|
void* target_surface,
|
|
VideoFrame& output_frame) {
|
|
// Step 1: Handle NULL packet as flush mode
|
|
if (!packet_data || packet_size == 0) {
|
|
m_state = DecoderState::FLUSHING;
|
|
}
|
|
|
|
// Step 2: Submit packet to NVDEC parser
|
|
// ...
|
|
|
|
// Step 3: Check if initial buffering is needed
|
|
{
|
|
std::lock_guard<std::mutex> lock(m_displayMutex);
|
|
|
|
// Transition from READY to BUFFERING on first packet
|
|
if (m_state == DecoderState::READY && m_displayQueue.empty()) {
|
|
m_state = DecoderState::BUFFERING;
|
|
}
|
|
|
|
// During initial buffering, accept packets until display queue has frames
|
|
if (m_displayQueue.empty() && m_state == DecoderState::BUFFERING) {
|
|
// Return false to indicate no frame yet (still buffering)
|
|
return false; // ← VAVCORE_PACKET_ACCEPTED로 변환됨
|
|
}
|
|
|
|
// Once we have frames in queue, transition to DECODING
|
|
if (!m_displayQueue.empty() && m_state == DecoderState::BUFFERING) {
|
|
m_state = DecoderState::DECODING;
|
|
}
|
|
}
|
|
|
|
// Step 4: Pop from display queue to get picture_index (PTS-ordered)
|
|
DisplayQueueEntry entry;
|
|
{
|
|
std::lock_guard<std::mutex> lock(m_displayMutex);
|
|
|
|
if (m_displayQueue.empty()) {
|
|
if (m_state == DecoderState::FLUSHING) {
|
|
// Return false - VAVCORE_END_OF_STREAM로 변환됨
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// Pop from priority queue (PTS-ordered)
|
|
entry = m_displayQueue.top();
|
|
m_displayQueue.pop();
|
|
}
|
|
|
|
// Step 5: Copy from CUDA DPB to target surface
|
|
if (!CopyFromCUDADPB(pic_idx, slot.surface_type, slot.target_surface, output_frame)) {
|
|
return false;
|
|
}
|
|
|
|
return true; // Frame successfully rendered
|
|
}
|
|
```
|
|
|
|
**핵심 특징**:
|
|
- ✅ **State Machine**: READY → BUFFERING → DECODING → FLUSHING
|
|
- ✅ **False Return**: 버퍼링/플러싱 시 false 반환 (정상 동작)
|
|
- ✅ **DisplayQueue**: PTS 기반 min-heap으로 B-frame 리오더링
|
|
- ✅ **Late Binding**: target_surface를 출력 직전에 업데이트
|
|
|
|
---
|
|
|
|
## 🚀 3. MediaCodec 개선 방향
|
|
|
|
### 3.1 State Machine 도입
|
|
|
|
```cpp
|
|
// MediaCodecAV1Decoder.h에 추가
|
|
enum class DecoderState {
|
|
READY, // Initialized and ready for first packet
|
|
BUFFERING, // Initial buffering (MediaCodec warming up)
|
|
DECODING, // Normal frame-by-frame decoding
|
|
FLUSHING // End-of-file reached, draining MediaCodec
|
|
};
|
|
|
|
private:
|
|
DecoderState m_state = DecoderState::READY;
|
|
std::mutex m_stateMutex;
|
|
```
|
|
|
|
### 3.2 DecodeToSurface() 리팩토링 (MediaCodec API 스펙 준수)
|
|
|
|
**핵심 원칙**: MediaCodec은 비동기 파이프라인 - Input/Output 분리
|
|
|
|
```cpp
|
|
bool MediaCodecAV1Decoder::DecodeToSurface(const uint8_t* packet_data, size_t packet_size,
|
|
VavCoreSurfaceType target_type,
|
|
void* target_surface,
|
|
VideoFrame& output_frame) {
|
|
if (!m_initialized) {
|
|
LogError("Decoder not initialized");
|
|
return false;
|
|
}
|
|
|
|
// Step 1: Handle NULL packet as flush mode
|
|
if (!packet_data || packet_size == 0) {
|
|
LOGF_DEBUG("[DecodeToSurface] NULL packet - flush mode (end of file)");
|
|
std::lock_guard<std::mutex> lock(m_stateMutex);
|
|
m_state = DecoderState::FLUSHING;
|
|
}
|
|
|
|
// Step 2: Update target surface BEFORE processing
|
|
// (MediaCodec needs surface configured before queueing input)
|
|
if (target_type == VAVCORE_SURFACE_ANDROID_NATIVE_WINDOW) {
|
|
ANativeWindow* native_surface = static_cast<ANativeWindow*>(target_surface);
|
|
if (native_surface && native_surface != m_surface) {
|
|
media_status_t status = AMediaCodec_setOutputSurface(m_codec, native_surface);
|
|
if (status != AMEDIA_OK) {
|
|
LogError("Failed to set output surface: " + std::to_string(status));
|
|
return false;
|
|
}
|
|
m_surface = native_surface;
|
|
LOGF_DEBUG("[DecodeToSurface] Output surface updated: %p", m_surface);
|
|
}
|
|
}
|
|
|
|
// Step 3: Process input buffer (feed packet to MediaCodec)
|
|
if (m_state != DecoderState::FLUSHING) {
|
|
if (!ProcessInputBuffer(packet_data, packet_size)) {
|
|
LogError("Failed to process input buffer");
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// Step 4: Check decoder state transition
|
|
{
|
|
std::lock_guard<std::mutex> lock(m_stateMutex);
|
|
|
|
// Transition from READY to BUFFERING on first packet
|
|
if (m_state == DecoderState::READY) {
|
|
m_state = DecoderState::BUFFERING;
|
|
m_bufferingPacketCount = 0;
|
|
LOGF_DEBUG("[DecodeToSurface] State transition: READY → BUFFERING");
|
|
}
|
|
}
|
|
|
|
// Step 5: Try to dequeue output buffer
|
|
// CRITICAL: MediaCodec is ASYNCHRONOUS - input/output are decoupled
|
|
// We must ALWAYS try dequeue, regardless of buffering state
|
|
bool hasFrame = ProcessOutputBuffer(output_frame);
|
|
|
|
if (!hasFrame) {
|
|
std::lock_guard<std::mutex> lock(m_stateMutex);
|
|
|
|
// Check state to determine return semantic
|
|
if (m_state == DecoderState::BUFFERING) {
|
|
m_bufferingPacketCount++;
|
|
LOGF_DEBUG("[DecodeToSurface] BUFFERING: packet %d accepted, no output yet",
|
|
m_bufferingPacketCount);
|
|
|
|
// Transition to DECODING when we get first output
|
|
// (will happen on next call when ProcessOutputBuffer succeeds)
|
|
|
|
return false; // VAVCORE_PACKET_ACCEPTED
|
|
}
|
|
|
|
if (m_state == DecoderState::FLUSHING) {
|
|
// Flush complete - no more frames
|
|
LOGF_INFO("[DecodeToSurface] Flush complete: all frames drained");
|
|
return false; // VAVCORE_END_OF_STREAM
|
|
}
|
|
|
|
// DECODING state but no output ready
|
|
LOGF_DEBUG("[DecodeToSurface] DECODING: packet accepted, output not ready");
|
|
return false; // VAVCORE_PACKET_ACCEPTED
|
|
}
|
|
|
|
// Step 6: First frame received - transition to DECODING
|
|
{
|
|
std::lock_guard<std::mutex> lock(m_stateMutex);
|
|
if (m_state == DecoderState::BUFFERING) {
|
|
m_state = DecoderState::DECODING;
|
|
LOGF_INFO("[DecodeToSurface] State transition: BUFFERING → DECODING (first frame)");
|
|
}
|
|
}
|
|
|
|
// Step 7: Frame successfully decoded - setup metadata
|
|
output_frame.width = m_width;
|
|
output_frame.height = m_height;
|
|
|
|
if (target_type == VAVCORE_SURFACE_ANDROID_NATIVE_WINDOW) {
|
|
output_frame.color_space = ColorSpace::EXTERNAL_OES; // Android SurfaceTexture
|
|
}
|
|
|
|
IncrementFramesDecoded();
|
|
LOGF_DEBUG("[DecodeToSurface] Frame %llu decoded successfully", m_stats.frames_decoded);
|
|
return true; // Frame successfully rendered
|
|
}
|
|
```
|
|
|
|
**주요 수정사항**:
|
|
1. ✅ **Surface 먼저 설정**: Input 큐잉 전에 target_surface 업데이트
|
|
2. ✅ **항상 Output Dequeue**: 버퍼링 중에도 `ProcessOutputBuffer()` 호출
|
|
3. ✅ **State 기반 Return**: BUFFERING/DECODING/FLUSHING에 따라 false 반환
|
|
4. ✅ **First Frame Transition**: 첫 프레임 출력 시 BUFFERING → DECODING
|
|
|
|
### 3.3 초기 버퍼링 제거 (MediaCodec API 특성)
|
|
|
|
**중요**: MediaCodec은 NVDEC과 다르게 **고정 버퍼링 카운트가 불필요**합니다.
|
|
|
|
**이유**:
|
|
```cpp
|
|
// MediaCodec은 비동기 파이프라인 - Input/Output 완전 분리
|
|
// - Input: dequeueInputBuffer → queueInputBuffer (즉시 리턴)
|
|
// - Output: dequeueOutputBuffer (프레임 준비 시 리턴)
|
|
//
|
|
// 첫 프레임 출력까지 자동으로 버퍼링하므로 별도 카운팅 불필요!
|
|
```
|
|
|
|
**개선된 State Transition**:
|
|
```cpp
|
|
// State는 Output 상태로만 판단
|
|
READY → BUFFERING (첫 packet 입력)
|
|
BUFFERING → DECODING (첫 frame 출력) ← ProcessOutputBuffer() 성공 시
|
|
DECODING → FLUSHING (NULL packet 입력)
|
|
```
|
|
|
|
**제거할 코드**:
|
|
```cpp
|
|
// ❌ 삭제: 불필요한 버퍼링 카운트
|
|
// #define VAVCORE_MEDIACODEC_INITIAL_BUFFERING 5
|
|
// int m_bufferingPacketCount;
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 4. B-frame 리오더링 고려사항
|
|
|
|
### 4.1 MediaCodec의 자동 리오더링
|
|
|
|
**NVDEC vs MediaCodec 차이**:
|
|
- **NVDEC**: 수동 리오더링 필요 (DisplayQueue + PTS 우선순위 큐)
|
|
- **MediaCodec**: 자동 리오더링 지원 (`AMediaCodec_getOutputBuffer()` 내부 처리)
|
|
|
|
**결론**: MediaCodec은 DisplayQueue 불필요!
|
|
- MediaCodec이 내부적으로 PTS 기반 리오더링 수행
|
|
- `BufferInfo.presentationTimeUs` 필드로 PTS 제공
|
|
- VavCore는 MediaCodec 출력 순서를 그대로 사용하면 됨
|
|
|
|
### 4.2 PTS 전달 개선
|
|
|
|
```cpp
|
|
// ProcessOutputBuffer 내부에서 PTS 추출 및 설정
|
|
bool MediaCodecAV1Decoder::ProcessOutputBuffer(VideoFrame& frame) {
|
|
// ... existing code ...
|
|
|
|
AMediaCodecBufferInfo bufferInfo;
|
|
ssize_t bufferIndex = AMediaCodec_dequeueOutputBuffer(m_codec, &bufferInfo, timeoutUs);
|
|
|
|
if (bufferIndex >= 0) {
|
|
// Extract PTS from MediaCodec
|
|
int64_t pts_us = bufferInfo.presentationTimeUs;
|
|
|
|
// Set frame metadata
|
|
frame.timestamp_ns = static_cast<uint64_t>(pts_us * 1000); // Convert µs to ns
|
|
frame.timestamp_seconds = static_cast<double>(pts_us) / 1000000.0;
|
|
|
|
// ... rest of processing ...
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 5. 구현 우선순위
|
|
|
|
### Phase 1: State Machine 도입 (필수) ✅ **COMPLETED** (2025-10-11)
|
|
- [x] `DecoderState` enum 정의 - MediaCodecAV1Decoder.h:33-38
|
|
- [x] `m_state` 멤버 변수 추가 - MediaCodecAV1Decoder.h:188
|
|
- [x] `m_stateMutex` 추가 - MediaCodecAV1Decoder.h:189
|
|
- [x] State transition 로직 구현 - MediaCodecAV1Decoder.cpp:44 (constructor)
|
|
|
|
### Phase 2: DecodeToSurface() 핵심 수정 (필수) ✅ **COMPLETED** (2025-10-11)
|
|
- [x] **Surface 먼저 설정**: Input 큐잉 전에 `AMediaCodec_setOutputSurface()` 호출 - line 220-229
|
|
- [x] **Output Dequeue 추가**: 버퍼링 중에도 `ProcessOutputBuffer()` 호출 - line 254
|
|
- [x] **State 기반 Return**: hasFrame 여부와 m_state로 false/true 결정 - line 256-271
|
|
- [x] **NULL packet 처리**: FLUSHING state transition - line 206-210
|
|
- [x] **State transition logic**: READY → BUFFERING → DECODING 구현 - line 242-280
|
|
|
|
### Phase 3: ProcessOutputBuffer() 활용 (필수) ✅ **ALREADY IMPLEMENTED**
|
|
- [x] `m_buffer_processor->DequeueOutputBuffer()` 반환값 확인 - line 838
|
|
- [x] PTS 메타데이터 이미 추출됨 (BufferProcessor에서 처리) - MediaCodecBufferProcessor.cpp
|
|
- [x] Surface rendering 시 `render=true` 플래그 확인 - MediaCodecBufferProcessor.cpp
|
|
|
|
### Phase 4: 불필요한 코드 제거 (권장) ⚠️ **NOT REQUIRED**
|
|
- [x] ~~MEDIACODEC_INITIAL_BUFFERING 상수~~ - 애초에 존재하지 않음
|
|
- [x] ~~m_bufferingPacketCount~~ - 애초에 존재하지 않음 (Output 상태로만 판단하는 설계 적용됨)
|
|
|
|
### Phase 5: 테스트 및 검증 (필수) ⏳ **PENDING**
|
|
- [ ] 단일 프레임 디코딩 테스트
|
|
- [ ] 초기 버퍼링 동작 검증 (자동 처리 확인)
|
|
- [ ] Flush mode 테스트 (EOF 처리)
|
|
- [ ] B-frame 비디오 재생 확인 (MediaCodec 자동 리오더링)
|
|
|
|
---
|
|
|
|
## ⚠️ 6. 주의사항
|
|
|
|
### 6.1 MediaCodec API 특성 (CRITICAL)
|
|
|
|
**MediaCodec은 비동기 파이프라인 - Input/Output 완전 분리**:
|
|
|
|
```cpp
|
|
// Input Pipeline (즉시 리턴)
|
|
AMediaCodec_dequeueInputBuffer() // 빈 버퍼 얻기
|
|
AMediaCodec_queueInputBuffer() // 패킷 큐잉 (즉시 리턴!)
|
|
|
|
// Output Pipeline (프레임 준비 시 리턴)
|
|
AMediaCodec_dequeueOutputBuffer() // 디코딩된 프레임 얻기 (대기 가능)
|
|
AMediaCodec_releaseOutputBuffer() // 프레임 렌더링 or 해제
|
|
```
|
|
|
|
**핵심 차이**:
|
|
- **NVDEC**: `cuvidParseVideoData()` → 동기 콜백 → 즉시 프레임 출력
|
|
- **MediaCodec**: `queueInputBuffer()` → 비동기 디코딩 → 나중에 `dequeueOutputBuffer()`
|
|
|
|
**설계 함의**:
|
|
1. ✅ `ProcessInputBuffer()` 성공 ≠ 프레임 출력 성공
|
|
2. ✅ 항상 `ProcessOutputBuffer()` 호출해야 프레임 얻을 수 있음
|
|
3. ✅ 초기 몇 개 패킷은 출력 없이 입력만 가능 (파이프라인 filling)
|
|
4. ✅ Flush 시에도 `dequeueOutputBuffer()` 호출해서 남은 프레임 드레인
|
|
|
|
### 6.2 NVDEC과의 차이점
|
|
|
|
| 항목 | NVDEC | MediaCodec |
|
|
|------|-------|------------|
|
|
| DPB 관리 | 수동 (CUDA DPB) | 자동 (MediaCodec 내부) |
|
|
| B-frame 리오더링 | 수동 (DisplayQueue) | 자동 (내부 처리) |
|
|
| 초기 버퍼링 | 16 프레임 | 5 프레임 (권장) |
|
|
| Flush 처리 | ENDOFSTREAM flag | `AMediaCodec_flush()` |
|
|
| 동기화 | cuvidGetDecodeStatus | dequeueOutputBuffer |
|
|
|
|
### 6.3 False Return 의미 변경
|
|
|
|
**기존 (잘못된 가정)**:
|
|
```cpp
|
|
// false = 에러 발생
|
|
// true = 성공
|
|
```
|
|
|
|
**개선 후 (NVDEC 모델 적용)**:
|
|
```cpp
|
|
// false = 프레임 없음 (버퍼링 중 or EOF)
|
|
// → VAVCORE_PACKET_ACCEPTED or VAVCORE_END_OF_STREAM
|
|
// true = 프레임 출력 성공
|
|
// → VAVCORE_SUCCESS
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 7. 예상 개선 효과
|
|
|
|
### 7.1 API 일관성
|
|
- ✅ NVDEC과 동일한 DecodeToSurface() 동작
|
|
- ✅ C API 래퍼에서 동일한 반환값 처리
|
|
- ✅ Vav2Player와의 통합 간소화
|
|
|
|
### 7.2 안정성 향상
|
|
- ✅ 초기 버퍼링 명확한 처리
|
|
- ✅ EOF/Flush 정확한 감지
|
|
- ✅ State Machine으로 예측 가능한 동작
|
|
|
|
### 7.3 성능 최적화
|
|
- ✅ 불필요한 디코딩 시도 제거
|
|
- ✅ 버퍼링 중 CPU 사용량 감소
|
|
- ✅ 프레임 드롭 최소화
|
|
|
|
---
|
|
|
|
## 📝 8. Next Actions
|
|
|
|
### Immediate (이번 작업)
|
|
1. State Machine enum 및 멤버 변수 추가
|
|
2. DecodeToSurface() 리팩토링 (false 반환 로직)
|
|
3. ProcessOutputBuffer() PTS 추출 개선
|
|
|
|
### Short-term (다음 작업)
|
|
1. 단위 테스트 작성 및 실행
|
|
2. Android Vulkan Player 통합 테스트
|
|
3. B-frame 비디오 검증
|
|
|
|
### Long-term (향후 개선)
|
|
1. Async mode 최적화 (MediaCodecAsyncHandler)
|
|
2. HardwareBuffer 연동 강화
|
|
3. Multi-codec 지원 (VP9, H.264)
|
|
|
|
---
|
|
|
|
**문서 버전**: 1.0
|
|
**최종 수정**: 2025-10-11
|
|
**작성자**: Claude Code (Sonnet 4.5)
|