FFmpeg Android Music Player Workspace

FFmpeg 네이티브 디코더와 Android 앱(music-player-ffmpeg-ndk)을 함께 관리하는 통합 워크스페이스입니다.
현재 구조는 ffmpeg-kit(FFmpeg 빌드)와 music-player-ffmpeg-ndk(앱)로 분리되어 있습니다.

Repository Layout

ffmpeg-android-maker-master/
├─ ffmpeg-kit/                  # FFmpeg Android 빌드 스크립트/소스/출력
│  ├─ ffmpeg-android-maker.sh
│  ├─ scripts/
│  ├─ docs/
│  └─ output/                   # 빌드 결과(기본 .gitignore 대상)
└─ music-player-ffmpeg-ndk/     # Android 앱(Compose + NDK + Service)
   └─ app/
      ├─ src/main/cpp/          # JNI/C++ (FFmpeg decode)
      ├─ src/main/java/         # Kotlin player/service/UI
      └─ src/main/jniLibs/      # APK에 포함되는 FFmpeg .so

Current Architecture (Validated)

1. 앱에서 SAF(OpenDocument)로 오디오 파일을 선택합니다.
2. PlaybackService가 파일 FD를 JNI로 전달합니다.
3. 네이티브(native_player.cpp)에서 FFmpeg(avformat/avcodec)로 디코딩합니다.
4. swresample로 출력 포맷으로 변환합니다.
5. Kotlin AudioOutputController가 JNI에서 PCM을 읽어 AudioTrack으로 출력합니다.
6. UI는 StateFlow로 상태/재생시간(positionUs, durationUs)을 표시합니다.

현재 앱 출력 정책:

• 입력 샘플레이트: 최대 384000 Hz
• 출력 채널: 원본 기준(모노/스테레오)
• 출력 인코딩: PCM_32BIT 고정 (디바이스 호환성 이슈 대응)

What Is Generated vs Versioned

• FFmpeg 원본 소스(ffmpeg-kit/sources)는 빌드 시 자동 다운로드됩니다.
• FFmpeg 빌드 산출물(ffmpeg-kit/output, ffmpeg-kit/build, ffmpeg-kit/stats)은 기본적으로 .gitignore 대상입니다.
• 앱에서 실제 패키징되는 라이브러리는 music-player-ffmpeg-ndk/app/src/main/jniLibs/arm64-v8a/*.so 입니다.

Prerequisites

Required

• Windows 10/11
• Android Studio (SDK/NDK 설치)
• JDK 17
• Git for Windows (Git Bash)
• Android SDK platform-tools (adb)

Environment Variables (Git Bash)

ffmpeg-kit/ffmpeg-android-maker.sh 실행 전에 필수:

export ANDROID_SDK_HOME="/d/Android/Sdk"
export ANDROID_NDK_HOME="/d/Android/Sdk/ndk/26.3.11579264"

Git Bash에서 gcc가 없으면(환경에 따라 필요):

export PATH="$PATH:/c/Users/<USER>/tools/w64devkit/w64devkit/bin"

Build Guide (End-to-End)

1) FFmpeg Build

ffmpeg-kit 디렉토리에서 실행:

cd /d/project_new/ffmpeg-android-maker-master/ffmpeg-kit

export ANDROID_SDK_HOME="/d/Android/Sdk"
export ANDROID_NDK_HOME="/d/Android/Sdk/ndk/26.3.11579264"
export PATH="$PATH:/c/Users/<USER>/tools/w64devkit/w64devkit/bin"

오디오 중심 최소 프로파일 예시:

export EXTRA_BUILD_CONFIGURATION_FLAGS="\
--disable-everything \
--disable-autodetect \
--disable-doc \
--disable-programs \
--disable-network \
--disable-postproc \
--disable-avdevice \
--disable-swscale \
--enable-avcodec \
--enable-avformat \
--enable-avutil \
--enable-swresample \
--enable-protocol=file \
--enable-protocol=pipe \
--enable-demuxer=flac \
--enable-demuxer=wav \
--enable-demuxer=mp3 \
--enable-demuxer=ogg \
--enable-demuxer=matroska \
--enable-demuxer=mov \
--enable-demuxer=aac \
--enable-demuxer=ape \
--enable-demuxer=wv \
--enable-decoder=flac \
--enable-decoder=aac \
--enable-decoder=aac_fixed \
--enable-decoder=mp3 \
--enable-decoder=mp3float \
--enable-decoder=vorbis \
--enable-decoder=opus \
--enable-decoder=alac \
--enable-decoder=ape \
--enable-decoder=wavpack \
--enable-decoder=pcm_s16le \
--enable-decoder=pcm_s24le \
--enable-decoder=pcm_s32le \
--enable-decoder=pcm_f32le \
--enable-decoder=pcm_f64le \
--enable-parser=flac \
--enable-parser=aac \
--enable-parser=mpegaudio \
--enable-parser=opus \
--enable-parser=vorbis"

./ffmpeg-android-maker.sh -abis=arm64-v8a

빌드 결과 확인:

ls output/lib/arm64-v8a
ls output/include/arm64-v8a/libavcodec/avcodec.h
cat stats/text-relocations.txt

2) FFmpeg .so 를 앱에 반영

앱 런타임은 jniLibs의 .so를 사용하므로, FFmpeg 빌드 후 복사가 필요합니다.

mkdir -p ../music-player-ffmpeg-ndk/app/src/main/jniLibs/arm64-v8a
cp output/lib/arm64-v8a/*.so ../music-player-ffmpeg-ndk/app/src/main/jniLibs/arm64-v8a/

참고:

• CMake 헤더 경로는 앱에서 자동 참조:
  • 우선: <repo>/ffmpeg-kit/output/include/${ANDROID_ABI}
  • 호환 fallback: <repo>/output/include/${ANDROID_ABI}

3) 앱 컴파일

PowerShell:

cd d:\project_new\ffmpeg-android-maker-master\music-player-ffmpeg-ndk
.\gradlew.bat clean assembleDebug

4) 디바이스 설치 및 실행

.\gradlew.bat installDebug
adb shell am start -W -n com.iriver.musicplayerffmpegndk/.MainActivity

확인:

adb shell pidof com.iriver.musicplayerffmpegndk
adb logcat -d | findstr MPFFmpeg

Build/Run Troubleshooting

libavcodec/avcodec.h not found

• 원인: 헤더 경로가 이전 레이아웃(../output/include/...)만 바라보는 경우
• 조치: 앱 CMake가 ffmpeg-kit/output/include/${ANDROID_ABI}를 우선 참조하도록 유지

24bit 파일(예: 24/44100) 무음

• 원인: 일부 디바이스의 AudioTrack 24bit packed 호환성 이슈
• 현재 정책: 앱 출력 PCM_32BIT 고정

Git Bash에서 gcc 관련 오류

• 원인: 기본 Git Bash에는 GCC toolchain 미포함
• 조치: w64devkit 설치 후 bin 경로를 PATH에 추가

Couldn't delete ... R.jar (Windows)

• 원인: 파일 잠금(IDE/백신/탐색기/백그라운드 Java 프로세스)
• 조치:
  • .\gradlew.bat --stop
  • Android Studio 종료 후 재시도
  • 잠금 프로세스 정리 후 빌드 재실행

Key Source References

• FFmpeg 빌드 진입점: ffmpeg-kit/ffmpeg-android-maker.sh
• 빌드 인자 파싱: ffmpeg-kit/scripts/parse-arguments.sh
• ABI별 환경 export: ffmpeg-kit/scripts/export-build-variables.sh
• 앱 네이티브 디코더: music-player-ffmpeg-ndk/app/src/main/cpp/native_player.cpp
• 앱 오디오 출력: music-player-ffmpeg-ndk/app/src/main/java/com/iriver/musicplayerffmpegndk/player/AudioOutputController.kt
• 포그라운드 서비스: music-player-ffmpeg-ndk/app/src/main/java/com/iriver/musicplayerffmpegndk/player/PlaybackService.kt
• 앱 CMake 연동: music-player-ffmpeg-ndk/app/src/main/cpp/CMakeLists.txt
• Windows 실빌드 문서: ffmpeg-kit/docs/BUILD_WINDOWS_GIT_BASH.md

License

• ffmpeg-kit 스크립트 자체: MIT (LICENSE.txt)
• 빌드된 FFmpeg 바이너리 라이선스: FFmpeg 설정에 따라 LGPL/GPL 달라질 수 있음