S3-compatible storage—One sink, every S3-API-speaking backend.

What it does

Upload every extracted frame to an S3-compatible bucket under a deterministic `runs/{id}/frame_NNNN.jpg` prefix. Plays nicely with any gateway that implements the AWS SigV4 S3 API, including self-hosted MinIO.

When to reach for it

• Durable cold storage for long-running agent sessions
• Share frames across a team by bucket ACL instead of file transfer
• Feed a CDN or a vector-embedding pipeline downstream

Install

npm i -g peepshow
npm i -g @aws-sdk/client-s3

Use it

peepshow ./clip.mov --sink s3 \
  --sink-arg bucket=my-peepshow \
  --sink-arg endpoint=https://nyc3.digitaloceanspaces.com

Make it automatic

Register the sink once — every run fires it afterward. Scope by--whenso it only runs for matching videos.

peepshow sinks add s3
peepshow sinks add s3 --when extension=mp4,mov
peepshow sinks add s3 --when path=/Volumes/Work/

Configuration

• AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEYCredentials for the bucket.required
• AWS_REGIONRegion, required for AWS; arbitrary for most S3-compatible services.required
• PEEPSHOW_S3_BUCKETBucket name (alternative to `--sink-arg bucket`).
• PEEPSHOW_S3_ENDPOINTNon-AWS endpoint URL for R2, MinIO, DO Spaces, etc.

Write your own

A sink is any executable that reads the--emit jsonpayload on stdin. Shell, Node, Python, Go — the spec's indocs/PLUGINS.md. Register persistent ones withpeepshow sinks add-cmd 'your-command'.