일반적인 문제 해결

이 문서는 FlowPick 사용 과정에서 발생할 수 있는 다양한 문제를 증상별로 분류하여 진단 단계와 해결 방안을 제공합니다.

문제 빠른 인덱스

문제 유형을 이미 알고 있다면 해당 섹션으로 바로 이동할 수 있습니다:

진단 도구와 팁

심층적인 문제 해결에 앞서 다음 진단 도구를 숙지하면 효율성을 크게 높일 수 있습니다.

브라우저 개발자 도구

F12 또는 Ctrl+Shift+I를 눌러 개발자 도구를 열고 다음 패널에 주목하십시오:

일반적인 오류 메시지 빠른 참조

Console에서 다음 오류가 보일 때 빠르게 문제를 파악할 수 있습니다:

진단 보고서 생성

복잡한 문제에 직면했을 때 Console에서 다음 코드를 실행하여 진단 보고서를 생성하고 Issue 제출에 활용할 수 있습니다:

// FlowPick 진단 보고서 생성기
const report = {
  userAgent: navigator.userAgent,
  platform: navigator.platform,
  language: navigator.language,
  fsaAvailable: 'showDirectoryPicker' in window,
  fsaSaveAvailable: 'showSaveFilePicker' in window,
  sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
  crossOriginIsolated: self.crossOriginIsolated,
  serviceWorker: 'serviceWorker' in navigator,
  storage: {
    quota: await navigator.storage?.estimate().catch(() => null),
  },
  timestamp: new Date().toISOString(),
}
console.log('FlowPick 진단 보고서:', JSON.stringify(report, null, 2))

미디어 검출 문제

확장 프로그램이 미디어를 검출하지 못함

증상: 비디오/오디오가 포함된 웹페이지를 연 후 FlowPick 아이콘을 클릭했을 때 팝업 창에 "미디어 리소스가 검출되지 않았습니다"라고 표시됩니다.

진단 단계:

1. 페이지에 미디어 로드 확인
   FlowPick을 열기 전에 비디오나 오디오를 몇 초간 재생하십시오. 많은 웹사이트는 Lazy Loading 전략을 사용하여 사용자 상호작용 후에야 미디어 스트림을 로드하기 시작합니다.
2. 페이지 새로 고침 후 재시도
   확장 프로그램의 미디어 검출은 네트워크 요청 모니터링에 의존합니다. 페이지 로드 후에 확장 프로그램이 설치되거나 활성화된 경우 초기 요청을 놓칠 수 있습니다. 페이지 새로 고침은 새로운 네트워크 요청을 트리거합니다.
3. 확장 프로그램 활성화 확인
   확장 프로그램 아이콘을 클릭할 때 팝업 창이 정상적으로 표시되는지 확인하십시오. 팝업 창이 열리지 않으면 확장 프로그램이 올바르게 설치되지 않았거나 비활성화된 것입니다.
4. 비표준 프로토콜 사용 여부 확인
   일부 웹사이트는 WebSocket, WebRTC 또는 커스텀 암호화 프로토콜로 미디어를 전송하는데, 이는 FlowPick의 검출 범위에 속하지 않습니다.

일반적인 원인과 해결 방안:

일부 미디어가 검출되지 않음

증상: FlowPick이 일부 리소스는 검출했지만 예상되는 특정 비디오나 오디오가 누락되었습니다.

가능한 원인:

• 동적 로드 타이밍: 특정 미디어는 사용자 스크롤이나 클릭 후에 로드됩니다. 페이지와 상호작용한 후 FlowPick을 여십시오
• 필터 설정: 최소 파일 크기 필터가 설정되어 작은 파일이 제외되었는지 확인하십시오. 필터 구성에 대해서는 구성 참조 — 필터 설정을 참조하십시오
• 비표준 MIME 타입: 서버가 반환하는 Content-Type이 FlowPick 인식 목록에 없습니다. FlowPick은 현재 25개 이상의 MIME 타입을 인식하지만 일부 CDN은 비표준 타입을 사용할 수 있습니다

이미지 검出不완전

증상: 페이지의 이미지가 검출 결과에 모두 나타나지 않습니다.

원인 분석:

• CSS background-image의 이미지는 페이지가 완전히 렌더링된 후에야 검출 가능
• Lazy Loading 이미지(loading="lazy")는 뷰포트로 스크롤해야 로드됨
• JavaScript로 동적으로 생성된 <img> 요소는 확장 프로그램 스캔 후 DOM에 삽입될 수 있음
• Canvas로 그린 이미지 내용은 DOM 검출로 가져올 수 없음

권장 사항: 페이지 전체를 스크롤하면서 본 후 FlowPick을 열어 모든 Lazy Loading 콘텐츠가 트리거되었는지 확인하십시오.

다운로드 문제

다운로드가 시작되지 않음

증상: 다운로드 버튼을 클릭했을 때 반응이 없거나 즉시 오류가 표시됩니다.

진단 단계:

1. 브라우저 다운로드 설정 확인
   브라우저가 자동 다운로드를 차단하지 않았는지 확인하십시오. Chrome에서: 설정 → 개인정보 보호 및 보안 → 사이트 설정 → 자동 다운로드.
2. 디스크 공간 확인
   시스템 디스크에 충분한 여유 공간이 있는지 확인하십시오. 비디오 파일은 매우 클 수 있습니다(수 GB). 다운로드 전 공간이 충분한지 확인하십시오.
3. 다른 다운로드 확장 프로그램 충돌 확인
   일부 다운로드 관리 확장 프로그램이 다운로드 요청을 가로채거나 수정할 수 있습니다. 잠시 다른 다운로드 관련 확장 프로그램을 비활성화해 보십시오.
4. 브라우저 콘솔 오류 확인
   F12를 눌러 개발자 도구를 열고 Console 패널의 오류 정보를 확인하십시오. 일반적인 오류:
   • Failed to fetch: 네트워크 요청 실패
   • CORS error: 크로스 오리GIN 요청 차단됨
   • QuotaExceededError: 저장 공간 부족

다운로드 속도가 느림

증상: 다운로드 진행이 느리고 속도가 네트워크 대역폭보다 현저히 낮습니다.

영향 요인과 최적화 권장 사항:

진단 흐름:

다운로드 속도 느림
    │
    ├── 동시수 < 4?
    │   └── 예 → 동시수를 4-6으로 증가, 속도 변화 관찰
    │
    ├── 속도 변동 큼?
    │   └── 예 → CDN 속도 제한 가능, 동시수를 2-3으로 낮춰 시도
    │
    ├── 모든 다운로드가 느림?
    │   └── 예 → 네트워크 대역폭 확인, 대역폭 점유 앱 종료
    │
    └── 특정 웹사이트만 느림?
        └── 예 → 해당 웹사이트 CDN이 속도 제한 가능, 다른 화질 시도

다운로드 중간 실패

증상: 다운로드가 일정 비율 진행된 후 오류로 정지합니다.

일반적인 오류 및 처리:

HTTP 403 Forbidden

세그먼트 URL에 유효기간 token이 포함되어 있을 수 있으며, 만료 후 서버가 접근을 거부합니다. 해결 방안:

• 페이지 새로 고침로 새 스트림 주소 획득
• 가능한 빨리 다운로드 완료, token 만료 방지
• HLS 스트림의 경우 token은 통상 M3U8 플레이리스트에 포함되므로 플레이리스트 재획득으로 해결

HTTP 404 Not Found

세그먼트가 서버에서 삭제됨(라이브 재생에서 흔함). 해결 방안:

• 스트림이 여전히 사용 가능한지 확인
• 다른 화질 선택 시도(다른 화질은 다른 세그먼트 파일 사용 가능)

네트워크 연결 중단

자동 재시도 메커니즘이 일시적 네트워크 변동을 처리합니다. 지속적으로 실패할 경우:

• 네트워크 연결 안정성 확인
• 동시 스레드 수 낮춤, 동시 진행 연결 감소
• 방화벽 또는 프록시 설정 확인

CORS 오류

온라인 도구 버전은 브라우저 동일 출처 정책 제한을 받습니다. 해결 방안:

• 브라우저 확장 프로그램 버전 사용(확장 프로그램은 더 넓은 네트워크 권한 보유)
• 온라인 도구 사용 시 스트림 URL 서버가 크로스 오리GIN 요청 허용하는지 확인

다운로드한 파일 재생 불가

증상: 다운로드 완료되었지만 비디오/오디오 파일을 플레이어에서 열 수 없습니다.

진단 및 복구:

1. 다른 플레이어 시도
   특정 코딩이나 컨테이너 지원이 제한된 플레이어가 있습니다. 다음 플레이어로 테스트 권장:
   • VLC Media Player(호환성 최고)
   • MPC-HC
   • PotPlayer
2. 파일 크기 확인
   파일 크기가 명백히 예상보다 작은 경우(예: 몇 KB), M3U8 플레이리스트 파일을 다운로드했을 수 있습니다. 올바른 리소스 선택을 확인하십시오.
3. 다른 화질 시도
   특정 화질의 세그먼트에 코딩 문제가 있을 수 있습니다. 더 낮거나 높은 화질 버전 다운로드 시도.
4. VLC 복구 기능 사용
   VLC는 내장 AVI/MP4 복구 기능 제공:
   • VLC 열기 → 미디어 → 변환/저장
   • 파일 추가 → 변환/저장
   • 출력 형식 선택 → 시작
5. 병합 완전성 확인
   다운로드 중 브라우저 크래시나 네트워크 중단 시 병합이 불완전할 수 있습니다. 재다운로드로 통상 해결됩니다.

대용량 파일 다운로드 실패

증상: 대용량 파일(>1GB) 다운로드 시 브라우저가 멈추거나 크래시됩니다.

원인: Blob 모드에서 전체 파일을 메모리에 로드해야 다운로드를 트리거합니다. 초대형 파일의 경우 메모리 부족을 초래할 수 있습니다.

해결 방안:

• File System Access API의 디렉토리 저장 기능 사용, 파일을 디스크에 직접 쓰고 메모리 점유 없음
• 브라우저가 FSA API를 지원하지 않으면 FlowPick이 자동으로 StreamSaver.js 스트리밍 쓰기 사용
• 두 가지 스트리밍 쓰기 모두 불가능한 경우 Blob 모드는 1.5GB의 하드 제한이 있으며, 이 크기를 초과하는 파일은 거부됨

병합 문제

병합 후 비디오 음화면 동기화 불일치

증상: 비디오와 오디오 트랙에 시간 오프셋이 존재합니다.

원인: 통상 DASH 스트림에서 발생하며, 비디오와 오디오 세그먼트의 타임스탬프가 완전히 정렬되지 않습니다. FlowPick은 -c copy 모드로 병합하며 재코딩하지 않으므로 타임스탬프 오프셋을 수정할 수 없습니다.

해결 방안:

• 다른 화질 선택 시도(다른 화질의 음비디오 동기화가 다를 수 있음)
• FFmpeg 명령줄 도구로 수동 재코딩:

ffmpeg -i output.mp4 -c:v libx264 -c:a aac -async 1 fixed.mp4

병합 과정 멈춤

증상: 진행 바가 "병합 중" 단계에서 오랫동안 멈춰 있습니다.

원인 분석:

• FFmpeg WASM이 대량 세그먼트 처리 시 상당한 시간 소요
• 멀티 스레드 모드에서 SharedArrayBuffer 사용 불가 시 FFmpeg이 싱글 스레드로 폴백, 속도 현저히 저하
• 메모리 부족으로 WASM 실행 느려짐

권장 사항:

• 병합 완료까지 대기, 대용량 파일 병합은 수 분 소요 가능
• TS 출력 형식 선택 시 FFmpeg 트랜스코딩 건너뛰고 바이너리 연결(초단위 완료)
• 메모리 점유 탭 닫기

브라우저 호환성 문제

SharedArrayBuffer 사용 불가

증상: 콘솔에 SharedArrayBuffer is not defined 표시 또는 FFmpeg이 싱글 스레드 모드로 실행됩니다.

원인: SharedArrayBuffer는 페이지가 올바른 보안 헤더를 설정해야 합니다. FlowPick 웹사이트는 다음과 같이 구성되어 있습니다:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

배포 환경에 이 헤더들이 없으면 FFmpeg이 자동으로 싱글 스레드 모드로 폴백하며, 기능에는 영향이 없지만 속도가 느려집니다.

File System Access API 사용 불가

증상: "저장 디렉토리 선택" 버튼이 없거나 클릭 후 반응이 없습니다.

지원 현황:

지원하지 않는 브라우저에서 FlowPick은 자동으로 브라우저 기본 다운로드 방식을 사용합니다.

StreamSaver.js 작동 안 함

증상: 콘솔에 StreamSaver 관련 오류가 표시됩니다.

가능한 원인:

• Service Worker 등록 실패(일부 브라우저 정책 금지)
• mitm.html 페이지 로드 불가
• 브라우저가 WritableStream 지원 안 함

FlowPick은 자동으로 Blob 모드로 강등되며, 기능에는 영향이 없습니다.

확장 프로그램 특정 문제

확장 프로그램 아이콘 표시 안됨

1. 브라우저 도구 모음의 퍼즐 아이콘(확장 프로그램 관리) 클릭
2. FlowPick 찾기
3. 핀 아이콘을 클릭하여 도구 모음에 고정

확장 프로그램 자동 비활성화

Chrome은 다음 상황에서 확장 프로그램을 비활성화할 수 있음:

• 확장 프로그램 업데이트 후 새 권한 필요
• 브라우저가 의심스러운 행동 감지
• 개발자 모드 확장 프로그램이 브라우저 재시작 후 비활성화

해결 방안: chrome://extensions 페이지에서 FlowPick을 재활성화하십시오.

단축키 충돌

기본 단축키 Alt+Shift+F와 Alt+Shift+D는 다른 확장 프로그램 또는 시스템 단축키와 충돌할 수 있습니다.

수정 방법:

1. chrome://extensions/shortcuts 열기
2. FlowPick 찾기
3. 새 단축키 조합 설정

네트워크 문제 해결

프록시/VPN 환경

프록시 또는 VPN 사용 시 다운로드에 영향을 받을 수 있습니다:

기업 네트워크 환경

기업 네트워크는 통상 더 엄격한 보안 정책이 적용되어 다음 문제를 초래할 수 있음:

• 방화벽이 비표준 포트 차단: 일부 스트리밍이 비 80/443 포트 사용, 기업 방화벽에 의해 차단될 수 있음
• Service Worker 비활성화: 일부 기업 관리 정책이 Service Worker 금지, StreamSaver.js 사용 불가
• 확장 프로그램 설치 제한: 기업 관리 브라우저가 화이트리스트 외 확장 프로그램 설치 금지

권장 사항: 기업 네트워크 환경에서 우선적으로 온라인 도구 버전 사용(접근 가능한 경우)하거나 IT 부서에 네트워크 정책 문의하십시오.

도움 받기

위 방안으로 문제가 해결되지 않는 경우:

1. GitHub Issues에서 유사한 문제가 있는지 확인
2. 새 Issue 제출, 다음 정보 포함:
   • 브라우저 및 버전
   • FlowPick 버전
   • 문제 설명 및 재현 단계
   • 브라우저 콘솔 오류 로그(F12 → Console)
   • 문제 페이지 URL(공개 접근 가능한 경우)
   • 진단 보고서 출력 내용