Pacing
Provider quotas are far smaller than a real library. subtrace is built around that fact rather than fighting it.
The arithmetic
A 10,000-file library against a 100/day quota is a few months of unattended running. That is the shape of the problem, not a limitation of the tool. What subtrace gives you is that those months need no attention: state is durable, runs resume, and nothing is attempted twice.
The knobs
| Setting | Bounds |
|---|---|
run.max_per_run (or --limit) | one run |
providers.<name>.daily_cap | one provider, one UTC day |
run.interval | how often watch runs |
run.concurrency | parallel fetches inside a run |
run.retry_after_hours | how long a not_found/failed item waits |
run.max_attempts | when an item is given up on |
Two independent ceilings apply. max_per_run stops a single run; daily_cap
stops the day. With interval = "12h", max_per_run = 50, and a cap of 100,
the second run of the day exhausts the cap and later runs do nothing but scan.
Sensible shapes
Match the day, not the run. Set each daily_cap to your account’s real
quota, then let max_per_run × runs per day come out at or above it. The cap is
the real limit; max_per_run mostly bounds how long one run takes.
Keep concurrency modest. The default of 4 is a good balance: it hides network latency without hammering a provider. Raising it does not increase how much you can download — the cap does that.
Leave retry_after_hours alone. A week is a reasonable guess at how long it
takes for someone to upload a subtitle that did not exist. Retrying sooner
spends quota re-asking questions you already know the answer to.
Use --skip-scan for frequent runs. On a large or network-mounted library
the walk dominates the run. After the first run of the day the database already
knows what is pending.
Watching progress
subtrace statustracked (file × language) totals every row; pending is the backlog;
downloads today shows how much of each cap is spent. If pending is not
shrinking day to day, either every cap is being hit (expected — this is the
long haul) or items are landing in not_found, which points at naming rather
than pacing. See Naming and matching.
Fast-forwarding a subset
You do not have to wait for the queue to reach the thing you care about:
subtrace fetch --path "/media/TV Shows/1923 {tmdb-157744}" --limit 20
subtrace fetch --kind movie --lang esBoth still respect the daily cap.