Known Limitations & Caveats

This document summarizes technical limitations and known issues of the current FlowPick version. Understanding these limitations helps avoid unexpected situations during use.

Limitation Level Explanation

Each limitation in this document is classified into three levels based on impact:

File Size Limitations

Blob Mode Hard Limit

When browser doesn't support File System Access API or StreamSaver.js, FlowPick degrades to Blob mode for file writing. This mode has a hard size limit:

Cause: Blob mode requires loading entire file into memory; exceeding 1.5GB may cause browser crash or page unresponsiveness.

Solution: Use Chrome 86+ or Edge 86+, which support File System Access API for streaming writes of any file size.

Memory Pressure

Even when using streaming write, these factors still consume memory:

• Concurrently downloaded segment data (each segment typically 1-10MB)
• FFmpeg WASM runtime memory (approximately 200-400MB)
• Page UI and other components

Recommendations:

• When downloading very large files (>5GB), reduce concurrent thread count to 1-2
• Close other tabs consuming memory
• Avoid running multiple FFmpeg remuxing tasks simultaneously

Streaming Protocol Limitations

DRM Protected Content

FlowPick cannot handle the following types of protected content:

Detection Method: When <ContentProtection> tag appears in DASH manifest, downloader explicitly indicates unsupported.

Why Can't DRM Be Supported?

The core of DRM systems is Content Decryption Module (CDM), a built-in closed-source binary component in browsers. CDM is deeply bound to OS and hardware, responsible for decrypting protected content and outputting decoded frames directly to GPU; application layer cannot intercept or read decrypted data. This is DRM's design goal—ensuring content isn't intercepted throughout the entire chain from decryption to display.

AES-128 Encryption

FlowPick supports HLS AES-128 segment encryption, but with these limitations:

• Only supports METHOD=AES-128, not SAMPLE-AES
• Key files must be accessible via HTTP(S) directly
• Does not support key URLs requiring Cookie authentication (online tool mode)

Live Streams

FlowPick is primarily designed for VOD (Video on Demand) content:

• Live HLS streams can download cached segments, but cannot fetch future segments
• Live stream segment lists continuously update; downloader doesn't automatically track new segments
• Recommend waiting for live broadcast to end before downloading complete replay

Actual Effect of Live Stream Downloads:

During live broadcast (30 minutes played):
  M3U8 manifest contains last ~30 seconds of segments
  → Downloader can only get this 30 seconds of content
  → Cannot get previous or future segments

After broadcast ends:
  M3U8 manifest contains complete segment list
  → Downloader can get all content
  → Equivalent to VOD download

Separated Audio/Video Streams

Some DASH streams separate video and audio into independent AdaptationSets:

• Downloader will list video and audio streams separately
• Need to manually select matching video and audio streams
• Merge requires FFmpeg WASM, takes longer time
• If A/V duration mismatched, merge result may have A/V desync

Browser Limitations

File System Access API

On unsupported browsers, all downloads use Blob mode, subject to 1.5GB size limit.

SharedArrayBuffer

FFmpeg WASM multithreading mode requires SharedArrayBuffer, which requires website to set these HTTP response headers:

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

If these headers aren't set, FFmpeg automatically degrades to single-thread mode; merge speed reduced by approximately 40-60%.

Service Worker

StreamSaver.js depends on Service Worker. Following situations cause StreamSaver unavailability:

• Browser private browsing mode (some browsers restrict Service Worker)
• Enterprise policy disables Service Worker
• Website didn't correctly deploy mitm.html and streamsaver-sw.js

Network Limitations

CORS Cross-Origin Restrictions

Online tool mode (/m3u8-downloader, /dash-downloader) restricted by browser same-origin policy:

• If streaming server doesn't set Access-Control-Allow-Origin response header, requests will be blocked
• Some CDNs check Referer or Origin request headers
• Extension version not subject to this restriction because it uses extension permissions for requests

CORS Error Technical Principles:

Online tool (flowpick.app) requesting CDN (cdn.example.com):

Browser sends request → CDN returns segment data
                      ↓
              Browser checks response headers:
              Does Access-Control-Allow-Origin include flowpick.app?
                      ↓
              No → Browser blocks JavaScript from reading response
              Yes → Normal read

Extension version:
Extension makes requests via chrome.webRequest / chrome.fetch
→ Not subject to same-origin policy
→ Can read responses from any origin

Request Rate Limiting

Some CDNs throttle high-frequency requests:

• High concurrent thread count may trigger 429 (Too Many Requests) errors
• Recommend keeping concurrency at 4 or below
• If encountering throttling, reduce concurrency and retry

Segment URL Expiration

Segment URLs from some streaming services contain time-sensitive tokens:

• Segments cannot be downloaded after token expiration
• Expiration time typically ranges from minutes to hours
• Recommend starting download promptly after obtaining manifest
• If download interrupted too long, may need to re-fetch manifest

Typical Expiration Scenarios:

Format Conversion Limitations

FFmpeg WASM Performance

FFmpeg runs as WebAssembly in browser, performance far below native version:

Reasons for Performance Difference:

1. WASM execution overhead: WebAssembly runs in browser sandbox, instruction execution efficiency approximately 70-80% of native
2. SIMD limitations: FFmpeg heavily uses SIMD instruction optimization; WASM SIMD support less comprehensive than native
3. Memory access: WASM linear memory model differs from native memory management
4. I/O bottleneck: Virtual filesystem read/write speed far below native filesystem

Unsupported Conversions

Following conversion paths currently unsupported:

• Any format → AVI, MOV, MKV, WebM
• Video codec conversion (e.g., H.264 → H.265)
• Audio codec conversion (e.g., AAC → MP3)
• Resolution scaling
• Adding watermarks or subtitles

FlowPick's FFmpeg integration focuses on container format conversion (remuxing), without involving encoding/decoding.

Remuxing vs Transcoding:

Remuxing (FlowPick supports):
  TS container → Extract H.264 video stream + AAC audio stream → Package into MP4 container
  Characteristics: No codec change, fast speed, lossless

Transcoding (FlowPick doesn't support):
  H.264 video stream → Decode → Re-encode as H.265 → Package
  Characteristics: Codec change, slow speed, lossy, CPU-intensive

Extension Version Limitations

Manifest V3 Limitations

FlowPick extension uses Chrome Manifest V3, subject to these platform limitations:

• Service Worker lifecycle limited (terminates after ~30 seconds idle)
• Cannot use persistent background page
• Network request monitoring relies on webRequest API

Impact of Manifest V3 on FlowPick:

Detection Scope

Extension's media detection relies on network request monitoring:

• Can only detect requests initiated after extension activation
• Page refresh allows re-detection
• Some websites using WebSocket or MSE may not have media URLs detected
• Media in iframes may be undetectable (depends on iframe's cross-origin policy)

Known Bugs

Large File Blob Download May Hang

Symptom: When downloading files approaching 1.5GB in Blob mode, browser may become unresponsive for extended periods.

Cause: new Blob([...]) construction requires copying all data; memory allocation and copying for large files takes considerable time.

Workaround: Use Chrome browser to enable streaming write.

Slow First FFmpeg Load

Symptom: First time using format conversion feature, FFmpeg loading takes 10-30 seconds.

Cause: FFmpeg WASM core files (~8MB) need to be downloaded from network and compiled.

Note: This is normal behavior; subsequent uses leverage browser cache, significantly improving load speed.

Load Time Breakdown:

First load:
  Download WASM file (~8MB)   →  2-5 seconds (depends on network speed)
  WASM compilation            →  5-15 seconds (depends on CPU)
  Initialize virtual FS       →  1-3 seconds
  Total                      →  10-30 seconds

Subsequent loads (cache hit):
  Read WASM from cache        →  <1 second
  WASM compilation (may cache) →  1-3 seconds
  Total                      →  2-5 seconds

Occasional CDN Segment Download Failures

Symptom: Individual segments return 503 or network errors during download.

Cause: CDN node temporary failure or network fluctuation.

Note: FlowPick has built-in 3-retry mechanism (exponential backoff); usually auto-recovers. If all retries fail, segment is skipped and logged.

Related Documentation

• Common Issues Troubleshooting — Diagnostic steps and solutions organized by symptom
• FAQ — High-frequency questions with concise answers
• Download Engine Architecture — Complete technical architecture of download engine
• Video Sniffing — HLS/DASH manifest parsing and encryption detection
• Format Conversion — FFmpeg WASM engine and output formats
• Batch Download — Queue scheduling and concurrency control
• Browser Compatibility — Browser API support and degradation strategies
• Online Tools — Online tool usage and limitations
• Privacy & Security — Permission explanation and privacy protection
• Configuration Reference — Concurrency, filter, and other settings
• Installation Guide — Extension installation and activation
• Live Replay Download — Very large file download scenarios
• Contributing Guide — How to report bugs and contribute code