Automatic timelapse
from any HLS stream

How it works

streamlapse is a zero-infrastructure pipeline built on two free tiers. GitHub Actions runs capture.py on a 5-minute cron. The script checks whether the current time falls inside your configured work hours and capture interval — if not, it exits with [SKIP]. If yes, ffmpeg pulls a single JPEG frame from your HLS stream and uploads it to Cloudflare R2. When you want a timelapse, you manually trigger generate.py — it downloads every frame for a date range, stitches them into an MP4, and uploads the result back to R2.

Frame path: screenshots/YYYY-MM-DD/HH-MM-SS.jpg  ·  Video path: videos/timelapse_<from>_to_<to>.mp4

Setup

1. Fork the repo and make it public

GitHub Actions on public repos have unlimited free minutes.

1. Click Fork on this GitHub repo
2. In your fork go to Settings → General and confirm visibility is Public
3. Complete the steps below, then push to main

2. Create a Cloudflare R2 bucket

1. Log in to dash.cloudflare.com → R2 Object Storage → Create bucket
2. Choose a name (e.g. my-streamlapse) and pick your region — EU, US, or APAC
3. Leave all other settings at defaults and click Create bucket

3. Create an R2 API token

1. Click Manage R2 API Tokens → Create API Token
2. Set Permissions: Object Read & Write and restrict to your specific bucket
3. Click Create API Token — copy the Access Key ID and Secret Access Key now (shown once only)
4. Copy the Jurisdiction-specific endpoint for S3 clients — this is your R2_ENDPOINT

Endpoint by bucket region:

4. Add GitHub Secrets

In your fork: Settings → Secrets and variables → Actions → New repository secret

5. Configure the schedule

Edit config.yml to match your timezone, active days, hours, and capture frequency. The GitHub Actions cron always fires every 15 minutes — all schedule logic runs inside capture.py, so you only ever edit config.yml.

schedule:
  timezone: 'Europe/Zagreb'          # any IANA timezone
  work_days: [Mon, Tue, Wed, Thu, Fri, Sat]
  work_hours:
    start: '07:00'
    end: '17:00'

capture:
  interval_minutes: 15   # 5, 10, 15, 30, or 60

6. Push and verify

After pushing go to Actions → Capture Frame → Run workflow. Outside configured work hours the run exits with [SKIP] — that is expected. Set the force dispatch input to true to bypass all checks for a quick test.

Generating a timelapse

Go to Actions → Generate Timelapse → Run workflow, fill in the optional inputs, and click Run workflow. When the run finishes the MP4 is available as a downloadable artifact in the run summary and is also uploaded to R2 under videos/.

Configuration reference

All tuneable settings live in config.yml at the root of the repo.

schedule:
  timezone: 'Europe/Zagreb'          # IANA timezone for work_days/work_hours checks
  work_days: [Mon, Tue, Wed, Thu, Fri, Sat]
  work_hours:
    start: '07:00'
    end: '17:00'

capture:
  interval_minutes: 15   # capture frequency (5, 10, 15, 30, or 60)
                         # cron fires every 15 min; this check runs in capture.py
  jpeg_quality: 3       # ffmpeg -q:v: 1 (best) – 31 (worst); 2–4 is a good range
  ffmpeg_timeout: 30    # seconds before giving up on the stream

storage:
  r2_prefix: 'screenshots'    # R2 key prefix for captured frames
  videos_prefix: 'videos'     # R2 key prefix for generated timelapse videos

generate:
  default_fps: 24              # output video frame rate
  video_scale: '1920:-2'       # width; -2 auto-scales height (must be divisible by 2)

Local development

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Set required environment variables
export STREAM_URL=https://example.com/stream.m3u8
export R2_ACCESS_KEY_ID=your_access_key_id
export R2_SECRET_ACCESS_KEY=your_secret_access_key
export R2_BUCKET_NAME=my-streamlapse
export R2_ENDPOINT=https://<account_id>.eu.r2.cloudflarestorage.com

# Test capture (--force bypasses work-hours and interval checks)
python scripts/capture.py --force

# Generate timelapse for a date range
python scripts/generate.py --date-from 2026-04-01 --date-to 2026-04-07 --fps 12