Download Engine Architecture

┌─────────────────────────────────────────────────┐
│                   Download Engine                 │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Segment   │→│ Segment   │→│ File Writing    │  │
│  │ Download  │  │ Process  │  │ Module          │  │
│  │ Module    │  │ Module   │  │                 │  │
│  │          │  │          │  │                 │  │
│  │ · Concur- │  │ · Decrypt│  │ · FSA Streaming│  │
│  │   rency  │  │ · Concat │  │ · StreamSaver   │  │
│  │ · Retry  │  │ · Remux  │  │ · Blob Fallback │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │           Memory Safety Manager              │ │
│  │  · Size Estimation · Threshold Check        │ │
│  │  · Strategy Selection                       │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

User clicks download
    │
    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 1. Manifest   │ ──→ │ 2. Segment    │ ──→ │ 3. Segment    │
│    Parsing    │     │    Download   │     │    Processing │
│              │     │               │     │               │
│ · Download   │     │ · Worker Pool │     │ · AES Decrypt │
│   M3U8       │     │ · Concurrency │     │ · TS Concat   │
│ · Parse seg- │     │ · Exponential │     │ · FFmpeg Remux│
│   ment list  │     │   backoff     │     │ · A/V Merge   │
│ · Extract    │     │ · Progress    │     │               │
│   key        │     │   reporting   │     │               │
│ · Estimate   │     │               │     │               │
│   size       │     │               │     │               │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 6. Completion │ ←── │ 5. Cleanup   │ ←── │ 4. File Write │
│ Notification │     │ & Recycling   │     │               │
│              │     │               │     │               │
│ · Desktop    │     │ · Release     │     │ · FSA Stream  │
│   notifi-    │     │   memory      │     │ · StreamSaver │
│   cation    │     │ · Clean temp  │     │ · Blob Fall-  │
│ · Copy path  │     │   files       │     │   back        │
│ · Queue adv- │     │ · Reset state │     │               │
│   ance       │     │               │     │               │
└──────────────┘     └──────────────┘     └──────────────┘

  [Idle]
    │ User triggers download
    ▼
  [Initializing] ─── Load WASM, check API availability, select write strategy
    │
    ▼
  [Manifest Parsing] ── Download and parse M3U8/MPD, extract segment list and keys
    │
    ▼
  [Segment Download] ── Worker Pool concurrent download, real-time progress reporting
    │
    ▼
  [Segment Processing] ── Decrypt → Concat/Remux → Write to disk
    │
    ├── Success → [Cleanup] → [Complete] → [Idle]
    │
    ├── Cancel → [Cleanup] → [Idle]
    │
    └── Failure → [Cleanup] → [Error] → [Idle]

const downloadSegmentsConcurrently = async (
  segments: SegmentInfo[],
  onSegmentDownloaded: (buffer: ArrayBuffer, index: number) => void
) => {
  const concurrency = Math.min(config.concurrency, 8)
  let nextIndex = 0

  const worker = async () => {
    while (nextIndex < segments.length) {
      const index = nextIndex++
      const buffer = await downloadWithRetry(segments[index]!)
      onSegmentDownloaded(buffer, index)
    }
  }

  const workers = Array.from(
    { length: Math.min(concurrency, segments.length) },
    () => worker()
  )
  await Promise.all(workers)
}

Pre-splitting (Not recommended):
Worker 1: [Segment 0-49]   ← If these segments are larger, Worker 1 becomes bottleneck
Worker 2: [Segment 50-99]  ← May finish early, then wait idle

Shared Counter (FlowPick's approach):
Worker 1: Segment 0 → Segment 3 → Segment 5 → ...
Worker 2: Segment 1 → Segment 4 → Segment 7 → ...
Worker 3: Segment 2 → Segment 6 → Segment 8 → ...

async function* segmentGenerator(
  segments: SegmentInfo[],
  signal?: AbortSignal
): AsyncGenerator<ArrayBuffer> {
  for (const segment of segments) {
    if (signal?.aborted) break
    const buffer = await downloadWithRetry(segment)
    yield buffer
  }
}

const downloadWithRetry = async (
  segment: SegmentInfo,
  maxRetries = 3
): Promise<ArrayBuffer> => {
  let lastError: unknown
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await downloadAndDecryptSegment(segment)
    } catch (e) {
      lastError = e
      if (attempt < maxRetries - 1) {
        // Exponential backoff: 400ms, 800ms, 1600ms
        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 400))
      }
    }
  }
  throw lastError
}

class FetchError extends Error {
  constructor(
    message: string,
    public status: number,
    public url: string
  ) {
    super(message)
    this.name = 'FetchError'
  }
}

const decryptAES128 = async (
  encryptedData: ArrayBuffer,
  key: ArrayBuffer,
  iv?: Uint8Array
): Promise<ArrayBuffer> => {
  const keyBytes = await crypto.subtle.importKey(
    'raw', key,
    { name: 'AES-CBC' },
    false,
    ['decrypt']
  )

  const ivBuffer = iv ? new Uint8Array(iv) : new Uint8Array(16)

  const decrypted = await crypto.subtle.decrypt(
    { name: 'AES-CBC', iv: ivBuffer },
    keyBytes,
    encryptedData
  )

  return decrypted
}

// Pseudocode
const merged = new Uint8Array(totalSize)
let offset = 0
for (const segment of segments) {
  merged.set(new Uint8Array(segment), offset)
  offset += segment.byteLength
}

HLS stream processing:
  Segment 0 → Segment 1 → Segment 2 → ... → Concat → Output

DASH stream processing (audio-video separated):
  Init segment → Video Seg 0 → Video Seg 1 → ... ─┐
                                              ├→ FFmpeg Merge → Output
  Init segment → Audio Seg 0 → Audio Seg 1 → ... ─┘

async function createFSAStream(
  filename: string,
  dirHandle?: FileSystemDirectoryHandle | null
): Promise<WritableStream<Uint8Array>> {
  let handle: FileSystemFileHandle

  if (dirHandle) {
    // Already have directory permission, directly create file
    handle = await dirHandle.getFileHandle(filename, { create: true })
  } else {
    // Popup for user to choose save location
    handle = await window.showSaveFilePicker!({
      suggestedName: filename,
      types: [{
        description: 'Video',
        accept: { 'video/mp4': ['.mp4'] }
      }]
    })
  }

  const writable = await handle.createWritable()

  return new WritableStream<Uint8Array>({
    async write(chunk) { await writable.write(chunk) },
    async close() { await writable.close() },
    async abort(reason) { await writable.abort(reason) }
  }, {
    highWaterMark: 16 * 1024 * 1024 // 16MB buffer
  })
}

async function createStreamSaverStream(
  filename: string,
  fileSize?: number
): Promise<WritableStream<Uint8Array>> {
  const ss = await getStreamSaver()
  const fileStream = ss.createWriteStream(filename, { size: fileSize })
  return fileStream
}

// Pseudocode
const blob = new Blob([mergedData], { type: 'video/mp4' })
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = filename
a.click()
URL.revokeObjectURL(url)

async function estimateSegmentsSize(
  segments: ArrayBuffer[] | AsyncGenerator<ArrayBuffer>,
  totalCount: number
): Promise<{ estimatedSize: number; isEstimate: boolean }> {
  // Sample count: min(5, max(1, totalCount * 0.1))
  const sampleCount = Math.min(5, Math.max(1, Math.floor(totalCount * 0.1)))

  // Download first few segments and calculate average size
  let sampledTotal = 0
  for (let i = 0; i < sampleCount; i++) {
    sampledTotal += sampleSegment.byteLength
  }

  const avgSample = sampledTotal / sampleCount
  return {
    estimatedSize: Math.round(avgSample * totalCount),
    isEstimate: true
  }
}

Estimated size < 800MB  → Any strategy acceptable
Estimated size 800MB-1.5GB → Prioritize streaming write, Blob mode shows warning
Estimated size > 1.5GB → Force streaming write, Blob mode refused

const MEMORY_CONFIG = {
  maxBlobSize: 1500 * 1024 * 1024,    // 1.5GB hard limit
  warnBlobSize: 800 * 1024 * 1024,    // 800MB warning threshold
}

const checkMemoryPressure = (): 'normal' | 'warning' | 'critical' => {
  // Check current total allocated segment buffer size
  const allocatedMB = allocatedBuffers.reduce((sum, buf) => sum + buf.byteLength, 0) / 1048576

  if (allocatedMB > 1200) return 'critical'
  if (allocatedMB > 600) return 'warning'
  return 'normal'
}

class SpeedCalculator {
  private samples: Array<{ bytes: number; timestamp: number }> = []
  private readonly WINDOW_SIZE = 5000 // 5 second window

  record(bytesDownloaded: number): void {
    this.samples.push({ bytes: bytesDownloaded, timestamp: Date.now() })
    // Remove samples older than window
    const cutoff = Date.now() - this.WINDOW_SIZE
    this.samples = this.samples.filter(s => s.timestamp >= cutoff)
  }

  getSpeed(): number {
    if (this.samples.length < 2) return 0
    
    const oldest = this.samples[0]!
    const newest = this.samples[this.samples.length - 1]!
    
    const timeDiff = (newest.timestamp - oldest.timestamp) / 1000 // seconds
    const byteDiff = newest.bytes - oldest.bytes
    
    return timeDiff > 0 ? byteDiff / timeDiff : 0
  }
}

function calculateETA(
  downloadedBytes: number,
  totalBytes: number,
  currentSpeed: number
): string {
  if (currentSpeed <= 0 || downloadedBytes >= totalBytes) return '--'
  
  const remainingBytes = totalBytes - downloadedBytes
  const remainingSeconds = remainingBytes / currentSpeed
  
  return formatDuration(remainingSeconds)
}

function formatDuration(seconds: number): string {
  if (seconds < 60) return `${Math.round(seconds)}s`
  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`
  return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`
}

interface DownloadProgress {
  // Basic info
  stage: 'parsing' | 'downloading' | 'processing' | 'writing' | 'completed'
  
  // Overall progress
  percent: number                    // 0-100
  downloadedBytes: number            // Total downloaded bytes
  totalBytes: number                // Estimated or exact total
  
  // Speed info
  speed: number                     // Bytes per second
  eta: number                       // Estimated remaining seconds
  
  // Segment-level detail
  completedSegments: number         // Completed segment count
  totalSegments: number             // Total segment count
  
  // Error info (if any)
  error?: {
    type: string
    message: string
    segmentIndex?: number
    recoverable: boolean
  }
}

const THROTTLE_INTERVAL = 100 // 100ms minimum interval

let lastEmitTime = 0
function emitProgress(progress: DownloadProgress) {
  const now = Date.now()
  if (now - lastEmitTime < THROTTLE_INTERVAL) return
  
  lastEmitTime = now
  eventEmitter.emit('progress', progress)
}

async function startDownload(
  url: string,
  options: DownloadOptions,
  signal: AbortSignal
): Promise<void> {
  // Pass signal to each module
  await parseManifest(url, { signal })
  await downloadSegments(segments, { signal })
  await processSegments(segments, { signal })
  await writeFile(outputFile, { signal })
}

User clicks cancel button
    │
    ▼
UI layer calls controller.abort()
    │
    ▼
1. Set signal.aborted = true
    │
    ├─→ 2. Stop accepting new download tasks
    │      └── Worker Pool stops grabbing new segments from queue
    │
    ├─→ 3. Interrupt ongoing fetch requests
    │      └── fetch() throws AbortError, caught by retry mechanism
    │
    ├─→ 4. Stop Worker Pool
    │      └── All Workers detect signal.aborted, exit loop
    │
    ├─→ 5. Clean up FFmpeg virtual filesystem
    │      └── Delete temp files: filelist.txt, segment_*.ts, output.*
    │
    ├─→ 6. Release allocated memory buffers
    │      └── Set all ArrayBuffer references to null, wait for GC
    │
    ├─→ 7. Discard incomplete file
    │      └── FSA mode: call writable.abort()
    │      └── StreamSaver mode: call writable.abort()
    │      └── Blob mode: Don't trigger download, release Blob directly
    │
    └─→ 8. Reset engine state
           └── Clear progress data, speed stats, error messages

UI Layer AbortController
    │
    ├──→ Segment Download Worker Pool (interrupt fetch)
    ├──→ Segment Processing Pipeline (skip remaining segments)
    ├──→ FFmpeg WASM (terminate remuxing)
    └──→ File Write Stream (abort write)

Concurrency 1: ████████████████████████████ Slow, low bandwidth utilization
Concurrency 2: ████████████████ Faster, basically usable
Concurrency 4: ██████████ Fast, recommended default
Concurrency 6: ████████ Very fast, near optimal
Concurrency 8: ████████ About same as 6, diminishing returns
Concurrency 12+: ████████ May trigger CDN throttling,反而 slower

┌─────────────────────────────────────────────┐
│                   UI Layer                  │
│  · Display user prompts (Toast/popup)       │
│  · Update download status to "failed"       │
│  · Provide retry/feedback entry points      │
└──────────────────┬──────────────────────────┘
                   │ Catch all exceptions
┌──────────────────▼──────────────────────────┐
│              Engine Facade Layer             │
│  · Unified exception format (StreamMergeError) │
│  · Attach context info (URL, segment index, stage) │
│  · Decide whether retryable                 │
└──────────────────┬──────────────────────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐  ┌──────────┐  ┌──────────┐
│Download│  │Process   │  │Write     │
│ Module │  │Module    │  │Module    │
│        │  │          │  │          │
│FetchErr│  │CryptoErr │  │WriteErr  │
└────────┘  └──────────┘  └──────────┘