Advanced Mode

Advanced Mode

You almost certainly don't need this page. Chaturdown works completely fine, indefinitely, without touching anything below — everyone starts on plain models.txt watching, and that's a perfectly good place to stay. This page exists for a handful of specific situations: you're watching a lot of rooms and hitting rate limits, you want long recordings automatically split into smaller files, you're tight on disk space, or you just want a more detailed dashboard. If none of that sounds like you, head back to Usage in the main README.

Every setting below lives in the same configuration block near the top of Chaturdown.py, further down from the basics covered in Configure. Every one of them defaults to being off — an unmodified Chaturdown.py behaves identically with or without this whole page existing.

Checking many rooms without hitting rate limits

USE_FOLLOWED_ROOMS_BULK_CHECK = False

By default, Chaturdown checks each models.txt username one at a time. If you're watching a lot of rooms, that's a lot of individual requests every poll cycle, which can occasionally trip Chaturbate's rate limiting. Setting this to True switches to a single request instead — the same one chaturbate.com/followed-cams/ itself uses — that reports every currently-online room the account behind Chaturdown_Cookies.txt follows.

The catch, and the reason this isn't the default: it only reports rooms that account actually follows. A models.txt username that isn't followed there will never be detected as online under this mode — it'll just look permanently offline, with no error to warn you. Only turn this on if every username in models.txt is followed on that account, or use it together with the next setting instead.

Watching everyone you follow, without listing them

AUTO_WATCH_FOLLOWED_ONLINE = False   # only does anything if USE_FOLLOWED_ROOMS_BULK_CHECK is also True

This solves the catch above a different way: instead of requiring models.txt to match your follow list, it automatically watches any followed room the bulk check above finds online — whether or not it's in models.txt — and stops watching it again once it's no longer online-and-followed. Nothing is ever written to models.txt; this only affects what Chaturdown watches in memory for the current run. Anything you do list in models.txt still works normally alongside it, followed or not.

Practical guidance — pick one of these two setups, not something in between:

• Manual control: both settings False. List exactly who you want in models.txt. No following required.
• Set-and-forget: both settings True. Follow whoever you want watched on the account behind Chaturdown_Cookies.txt; Chaturdown finds and records them automatically the moment they go live, and models.txt is only needed for anyone you want watched without following them.

Turning on AUTO_WATCH_FOLLOWED_ONLINE alone, without bulk-check, does nothing — there's no "who's followed" data to work from without it.

For example if you follow 20+ models and don't want to add each one to the models.txt file, just enable BULK and AUTO and Chaturdown will find them using your provided cookie file and will auto download when they go live. By default it checks every 1-2 minutes (randomized). Changeable by opening the .py file in a text editor and changing POLL_MIN = 60 and POLL_MAX = 120 (in seconds), saving then restarting the script. Don't set these too low though — querying Chaturbate too often can flag your account as a bot, which expires your cookies and means grabbing new ones before you can restart, annoying for something meant to be set-and-forget.

Splitting long recordings into multiple files

MAX_RECORDING_DURATION = 0    # seconds, 0 = unlimited (today's behavior: one continuous file)
MAX_RECORDING_SIZE_MB   = 0    # megabytes, 0 = unlimited

By default, a recording runs as one file for as long as the room stays live — that can mean a single multi-hour, multi-gigabyte file. Setting either of these starts a fresh, sequentially-numbered file (username_002.mkv, _003.mkv, …) once the current one hits the limit, with no gap in recording — useful if huge single files are awkward to move, edit, or upload. You can set one, the other, or both; whichever is hit first triggers the split. Note that the size limit can overshoot by a small amount — it's checked periodically, not on every byte written, so it can't cut off at the exact number.

Custom filenames

FILENAME_FORMAT = "{username}_{index:03d}"   # default naming, unchanged

Change how recordings are named. Available placeholders: {username}, {index} (auto-incrementing segment number — {index:03d} zero-pads it to 3 digits, e.g. 007), {date} (YYYY-MM-DD), {time} (HH-MM-SS), {yyyymmdd} (same as {date} with no separators, e.g. 20260808), and {hhmmss} (same as {time} with no separators, e.g. 160435) — all usable in any order.

Example: FILENAME_FORMAT = "{username}_{date}_{index:03d}" → some_model_2026-08-06_001.mkv, numbering restarting fresh each new date automatically.

{index} is optional. If it's present, Chaturdown finds the next free number for a user by matching the template against existing filenames — so {date}/{time}/{index} can appear in any order without confusing the count. If you leave {index} out entirely — e.g. FILENAME_FORMAT = "{username}-{yyyymmdd}-{hhmmss}" — the filename is built straight from the segment's start date/time instead, no scanning needed. The only edge case: if two segments would ever render to the exact same name (a duration/size-limit rotation landing in the same second as the file it's replacing), Chaturdown appends _02, _03, etc. rather than overwriting.

Changing FILENAME_FORMAT mid-run or between runs is always safe — files left over from a previous, differently-shaped template are simply ignored by the scan rather than affecting the new numbering.

Moving finished recordings out of the way

MOVED_DIR_STR      = ""     # e.g. "./Complete" or a path on another drive
MOVED_DIR_PER_USER = True

By default, every recording just stays in Videos/ forever, active or finished, with no way to tell them apart except checking whether yt-dlp still has the file open. Setting MOVED_DIR_STR moves each segment out of Videos/ and into this folder once it's actually done being written to — normal completion, a duration/size-limit rotation, or a stop/interruption all count, since the point is "not currently being recorded to," not "definitely a clean, complete file." Works across drives, so this can point somewhere else entirely — handy for keeping active recordings on fast storage and finished ones on a bigger, slower archive disk.

MOVED_DIR_PER_USER mirrors Videos/'s per-username subfolder layout inside the move target (MOVED_DIR/username/) when True; set False to dump every moved file directly into MOVED_DIR with no subfolders.

Stopping before you run out of disk space

LOW_DISK_SPACE_MB = 0    # megabytes, 0 = disabled (never checks free space)

Once free space on the drive holding your Videos/ folder drops below this many megabytes, Chaturdown stops starting new downloads (shown as LOW_DISK in the dashboard) and stops any download already in progress, gracefully — same as a normal stall. Recovers automatically once space frees up again. A typical real-world value is somewhere around 5000–10000 (5–10 GB) — enough headroom to avoid actually filling the disk, adjust to taste for how much buffer you want.

Dashboard extras

HIDE_OFFLINE_MODELS   = False   # hide offline rows entirely instead of showing them in red
SHOW_DOWNLOAD_SPEED   = False   # show an estimated MB/s next to each active download
SPEED_SAMPLE_INTERVAL = 2       # how often (seconds) the speed estimate re-samples; only matters if the above is True

Two independent cosmetic toggles for the TUI, useful once models.txt (or your follow list, under auto-watch) gets long — hiding offline rows keeps the dashboard to just what's actually recording, and the speed estimate gives a rough sense of transfer rate. The speed number is estimated from how fast the file on disk is growing, sampled every SPEED_SAMPLE_INTERVAL seconds — yt-dlp doesn't report a real speed figure with the downloader Chaturdown uses, so treat it as a useful approximation, not an exact reading.

Fixing fragmented recordings on flaky connections

USE_NATIVE_FETCHER = False   # requires native_fetch.py in the same folder as Chaturdown.py

By default, Chaturdown hands the whole download off to ffmpeg, including fetching the stream itself. On some setups — NAS boxes and other locked-down/resource-constrained environments have been the common thread so far — that produces choppy, fragmented recordings with dropped segments, and sometimes drifting or missing audio near the end of a file, even though the network connection itself is fine.

Setting this to True swaps in native_fetch.py, a purpose-built fetcher that replaces only ffmpeg's input side — muxing and output are completely untouched, same locked, audio-drift-tuned flags either way. It uses the CDN's low-latency blocking-reload delivery instead of guessing a poll interval, verifies every segment against its expected size and retries on a mismatch, and automatically re-resolves the playlist URL if its signed token expires mid-recording — none of which ffmpeg's own HLS demuxer does. Real-world testing on a NAS that was consistently producing fragmented, low-bitrate-audio recordings under the default engine found this fixed it outright (see GitHub issue #3): audio bitrate went from ~18kbps to a healthy ~128kbps, matching a reference recorder, with no more fragmentation.

Requires native_fetch.py downloaded and sitting in the same folder as Chaturdown.py. If it's missing, or this is turned on on Windows, Chaturdown refuses to start with a clear message instead of failing partway through a recording. Not supported on Windows — native_fetch.py relies on os.mkfifo(), which doesn't exist there.

This is newer and less battle-tested than the default engine, which is why it defaults to off instead of replacing it outright. If you're not seeing fragmented or out-of-sync recordings today, there's no reason to turn this on.

---

See also: Proxy · Troubleshooting · back to README