feat: add --from/--to video clipping flags

[RichardBray]

Summary

• Adds --from <MM:SS> and --to <MM:SS> CLI flags to clip downloaded videos to a time range
• Clipped files are saved with a _clip suffix (e.g. username_123_clip.mp4)
• HLS streams are clipped via ffmpeg using slow/accurate seek (-ss after -i) with re-encode to h264/aac for QuickTime compatibility
• MP4 streams download the full video via the existing HTTP downloader, then clip locally with ffmpeg
• showVersion() now reads from package.json instead of a hardcoded string

Test Plan

• x-dl --from 00:05 --to 00:10 <tweet-url> produces a ~5s clip in ~/Downloads
• Output file is named *_clip.mp4 and opens in QuickTime Player
• x-dl --help shows --from and --to in OPTIONS and CLIP EXAMPLES
• x-dl -v shows 0.4.4
• Downloads without --from/--to are unchanged

🤖 Generated with Claude Code

---

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 11 additional findings in Devin Review.

[devin-ai-integration]

🔴 No-progress timeout kills ffmpeg during slow HLS seek before encoding can start

When clipping an HLS stream with --from, the code uses slow/accurate seek (-ss after -i), which requires ffmpeg to download and decode the entire HLS stream up to the seek point before writing any output. During this seek phase, the output file either doesn't exist or contains only a tiny header and does not grow. The 60-second noProgressTimeoutMs poll at src/ffmpeg.ts:75-107 monitors output file size growth and will kill ffmpeg after 60 seconds of no growth, even though ffmpeg is actively downloading and decoding HLS segments.

Root Cause and Impact

The timeline for --from 05:00 on an HLS stream is:

1. lastProgressTime initialized to Date.now() at line 38
2. ffmpeg spawned — begins downloading HLS segments and decoding
3. Output file either doesn't exist yet or has a tiny ftyp header (~32 bytes)
4. 60 seconds later, poll at line 86/96 fires: now - lastProgressTime > noProgressTimeoutMs → ffmpeg killed with error "FFMPEG stuck: no progress for 60 seconds"

The previous 30-second timeout was fine because non-clipping HLS downloads use -c copy (stream copy), which writes output immediately. The PR increased it to 60s, but slow seek on HLS requires downloading the full input up to the seek point, which can take minutes for non-trivial --from values.

Impact: The HLS clipping feature is broken for any --from value where the HLS content before the seek point takes more than ~60 seconds to download and decode. For example, --from 05:00 would require downloading ~5 minutes of HLS segments before producing output, but ffmpeg is killed after 60 seconds.

Prompt for agents

In src/ffmpeg.ts, the noProgressTimeoutMs at line 36 needs to account for HLS slow seek. When clipping is active (clipFromSecs is defined), ffmpeg uses -ss after -i which means it must download and decode the entire stream up to the seek point before any output is written. The 60-second no-progress timeout kills ffmpeg before it can start encoding.

Possible fixes:
1. When isClipping is true (line 42), either disable the no-progress polling entirely, or scale the noProgressTimeoutMs based on clipFromSecs (e.g. clipFromSecs * 2 * 1000 + 60000) to give ffmpeg enough time to seek through the input.
2. Alternatively, monitor ffmpeg's stderr for progress information instead of polling output file size, since ffmpeg can report processing progress even during the seek phase.
3. As a simpler fix, set noProgressTimeoutMs to a much larger value (e.g. the full timeoutMs) when clipping is active, and rely solely on the overall timeout.

---

Was this helpful? React with 👍 or 👎 to provide feedback.