BBPlayer 개발 작업 보고 (2026-03-24 ~ 2026-03-25)¶

---

개요¶

항목	내용
프로젝트	BBPlayer
작업 기간	2026-03-24 ~ 2026-03-25
담당자	페후 (이태훈)
문서 버전	v3.7 → v4.13
대상 플랫폼	Android (주), Windows (보조)

---

완료된 기능 구현¶

1. Android 터치 제스처 제어 (v3.8)¶

- 단일 탭: 컨트롤 표시/숨김 토글
- 더블탭 좌: 10초 탐색
더블탭 우: +10초 탐색
- 수직 스와이프 좌반부: 화면 밝기 조절 (screen_brightness 패키지)
- 수직 스와이프 우반부: 볼륨 조절
- 수평 스와이프: 영상 탐색 (화면 가로 100% = 180초)
- 제스처 중 화면 중앙 아이콘+수치 오버레이 표시 (2초 자동 소멸)

---

2. Android 외부 앱에서 동영상 열기 — 인텐트 처리 (v3.9, v4.4)¶

- AndroidManifest.xml intent-filter 추가
- content:// scheme 명시 + BROWSABLE 카테고리
- file:// scheme
- http:// / https:// scheme (DS File 등 NAS 스트리밍 앱 대응)
- MainActivity에 MethodChannel (초기 실행 URI) + EventChannel (실행 중 수신) 구현
- content:// URI → MediaStore 경로 변환 처리

---

3. 비디오 프레임 캡처 (v4.0)¶

- player.screenshot()으로 UI 없이 순수 영상 프레임 추출
- Android/macOS: gal 패키지로 갤러리 저장 (BBPlayer 앨범)
- Windows: Pictures\BBPlayer\ 폴더 저장
- 상단 바 카메라 버튼 / C 단축키
- 저장 성공/실패 피드백 오버레이 2초 표시
- pubspec.yaml에 gal: ^1.2.0 추가, WRITE_EXTERNAL_STORAGE 권한 추가 (maxSdkVersion=29)

---

4. PIP (Picture in Picture) (v4.1, v4.2)¶

- AndroidManifest.xml에 supportsPictureInPicture="true" 추가
- MainActivity에 PIP MethodChannel + 상태 EventChannel 구현
- 영상 실제 비율(VideoParams.w/h)로 PictureInPictureParams.Rational 전달
- PIP 진입 시 컨트롤 전체 숨김, 해제 시 자동 복원
- 홈 버튼 자동 PIP: 영상 재생 중일 때만 진입 (setPlaying MethodChannel로 재생 상태 공유)

---

5. 재생 에러 오버레이 (v4.11)¶

- player.stream.error 구독
- 조건부 표시: 500ms 후에도 duration == 0인 경우만 표시 (파일 로드 실패)
- 재생 중 발생하는 mpv 경고성 메시지는 무시
- 에러 메시지 + 닫기 버튼 UI

---

6. 빌드 환경 개선 (v4.3, v4.5)¶

- Kotlin 증분 컴파일 비활성화: gradle.properties에 kotlin.incremental=false 추가
- C:/D: 드라이브 경로 충돌로 발생하는 Kotlin 데몬 캐시 오류 영구 해결
- 빌드 스크립트:
- build_android.bat: 빌드 후 BBPlayer.apk로 자동 복사 (call flutter 방식)
- build_windows.bat: Windows 빌드 래퍼
- CMakeLists.txt BINARY_NAME → BBPlayer 변경 (Windows EXE 파일명)

---

7. Android UI — 세로 모드 레이아웃 개선 (v4.6)¶

- MediaQuery.orientation 감지로 세로/가로 자동 전환
- 세로 모드: 하단 컨트롤 2줄 분리
- 1줄: 이전/±10초/재생/±10초/다음 (중앙 정렬)
- 2줄: 시간 표시 + 반복/셔플/속도 + 음소거 (볼륨 슬라이더 제거 — 제스처로 대체)
- 가로 모드: 기존 단일 행 유지

---

8. 시스템 UI Inset 적용 (v4.7)¶

- 상단/하단/좌우 MediaQuery.of(context).padding 반영
- 네비게이션 바, 노치, 카메라 컷아웃에 의한 버튼 가림 현상 해결
- 가로/세로 모드 모두 자동 대응

---

9. 수평 스와이프 실시간 영상 프리뷰 (v4.8, v4.12, v4.13)¶

- 드래그 중 _player.seek() 실시간 호출 → 영상 프레임 이동
- 드래그 시작 시 플레이어 pause() (오디오 완전 차단)
- 드래그 종료 시 재생 중이었던 경우만 play() 재개
- 볼륨 소실 버그 수정: setVolume(0) 호출 시 stream.volume이 _volume을 덮어쓰는 문제 → _horizDragSavedVolume에 사전 저장 방식으로 해결

---

10. 방향키 탐색 진행바 즉각 반영 (v4.9)¶

- _seekPreviewPos 상태 변수 추가
- 방향키 입력 시 진행바 즉시 이동 (디바운스 400ms 완료 이전에도 시각 반영)
- 실제 seek() 완료 후 _seekPreviewPos = null 초기화

---

11. 컨트롤 숨김 시 터치 차단 (v4.10)¶

- AnimatedOpacity를 IgnorePointer로 래핑
- 컨트롤 비표시 상태에서 진행바·버튼 터치 이벤트 완전 차단
- 비디오 영역 탭(컨트롤 재표시)은 GestureDetector가 상위 레이어에 있어 정상 동작 유지

---

버그 수정¶

#	증상	원인	해결
1	빌드 오류: VideoParams.width not found	media_kit 실제 필드명은 w/h	params.w, params.h로 수정
2	빌드 오류: Gal.putImageBytes name: not found	gal 1.9.1 API에 name 파라미터 없음	name: 제거, album: 만 사용
3	빌드 오류: Kotlin 데몬 캐시 충돌	C:/D: 드라이브 다른 루트 경로 충돌	kotlin.incremental=false
4	BBPlayer가 연결앱 목록에 미표시	scheme 미명시, BROWSABLE 누락	intent-filter 전면 재작성
5	DS File에서 BBPlayer 미표시	http/https scheme intent-filter 없음	http/https intent-filter 추가
6	스와이프 후 소리가 사라짐	setVolume(0) 시 _volume 상태 덮어쓰기	_horizDragSavedVolume 사전 저장
7	스와이프 중 빠른 오디오 재생	seek 사이 버퍼 오디오 재생	pause/resume 방식으로 전환
8	컨트롤 숨김 상태에서 진행바 터치됨	AnimatedOpacity는 터치 미차단	IgnorePointer 래핑
9	정상 재생 중 에러 오버레이 표시	stream.error 경고 메시지도 표시	duration==0 조건 추가
10	버튼이 시스템 UI에 가려짐	고정 padding 사용	MediaQuery.padding 동적 반영
11	build_android.bat 중간 종료	flutter가 .bat이므로 call 필요	call flutter 로 수정

---

변경된 파일 목록¶

파일	변경 내용
lib/screens/player_screen.dart	터치 제스처, PIP, 캡처, 에러 오버레이, 세로 UI, inset, 프리뷰 seek, IgnorePointer 등
lib/screens/home_screen.dart	인텐트 수신 처리 (MethodChannel + EventChannel)
android/app/src/main/AndroidManifest.xml	intent-filter, PIP, 권한 추가
android/app/src/main/kotlin/.../MainActivity.kt	PIP 채널, 인텐트 채널 전면 재작성
android/app/build.gradle.kts	Java/Kotlin 버전 11 설정
android/gradle.properties	kotlin.incremental=false 추가
windows/CMakeLists.txt	BINARY_NAME → BBPlayer
pubspec.yaml	screen_brightness, gal 패키지 추가
build_android.bat	신규 생성
build_windows.bat	신규 생성
개발계획서.md	v4.13으로 업데이트