Movie & TV Automation

RamTV can keep enriching, rating, subtitling — and in one optional case, sourcing — your catalogue on a schedule, without you touching each title by hand. Movie and TV each run their own automation engine, built on the same shared cronjob machinery, so almost everything below applies to both with only the object names swapped. This article covers setup end to end: the scheduler it depends on, how to actually build a job, worked examples, every credential you'll need and where to get it, and how to watch it work — plus the legal caveats around the scraper-based parts.

Before you start: a real scheduler

RamTV ships the automation logic but cannot trigger itself. An OS-level scheduler has to call RamTV's cron runner on an interval — commonly once a minute — for any of this to ever run. Until that's wired up, every cronjob below sits configured and idle no matter how you set it.

* * * * * php /path/to/ramtv/api/admin.php bof_cronjobs=yes >/dev/null 2>&1

That's the actual command, and it's the same on every BOF-based product — just point it at your own install's api/admin.php. On Linux, add a line like the one above with crontab -e. On Windows, point Task Scheduler at php.exe with that same file and argument, set to run every minute. Nothing in the rest of this article does anything until that's actually running.

Anatomy of a cronjob

Movie cronjobs and TV cronjobs are configured the same way, on their own screens: Admin area → Movies → Cronjobs and Admin area → TV → Cronjobs. Every job shares these fields:

Creating a cronjob, step by step

1. Go to Admin area → Movies → Cronjobs (or TV → Cronjobs) and press Create
2. Give it a name that says what it's for — "Seed", "Ratings refresh", "Trailer fetch"
3. Pick the Job — which API and object type it targets
4. If it's a TheMovieDB job, choose Static (paste ids one per line, or use Browse TheMovieDB — type a title, pick from the results, and its id is appended for you) or Dynamic (RamTV picks items out of your own database using filters). Every other job type is dynamic-only, working against titles you already have
5. Set Execution interval, Update interval and Item limit
6. Save, then use Activate on the list screen to switch it on

TheMovieDB automation

This is the job that does the most, and the only one that can create brand-new titles. movie_tmdb and tv_tmdb pull cast, crew, tags, recommended titles, similar titles, collections, external ids, logos and translations onto a movie or show. On TV specifically, the same job also creates the seasons and episodes underneath it — pointing a TV cronjob at a show's TheMovieDB id can build out its entire season/episode tree, not just the show's own page, which is worth knowing before you point one at a show with a hundred episodes and a low item limit. A parallel person_tmdb job keeps cast and crew filmographies current, capped by a Filmography limit setting (60 by default) so one prolific actor doesn't pull their entire back catalogue into your database in a single run.

Worked examples

A few concrete starting points, since the settings above read more abstractly than they behave in practice:

Example 1 — seeding a small catalogue

Create a Movie cronjob. Job: movie_tmdb. Dynamic IDs: off. Use Browse TheMovieDB to search and add the ten or twenty titles you want as your initial catalogue — each click appends that title's id to the Static IDs list. Save, then Activate. Each run brings in cast, artwork and everything else for whichever of those titles hasn't been checked yet, within your interval settings.

Example 2 — keeping ratings current without re-running TMDB

Once your titles carry TheMovieDB or IMDb ids, add a Dynamic imdb job (or mdblist, if you want several sites' scores in one call) with a long Update interval — ratings don't change hourly, so there's no reason to check daily. This keeps scores fresh without re-running the heavier TMDB job against titles that haven't actually changed.

Example 3 — building out a whole season automatically

For TV, a single Static tv_tmdb job pointed at one show's TheMovieDB id doesn't just refresh the show's own page — it creates every season and episode under it that TheMovieDB knows about. That's the fast way to bring in a series you only have the show-level details for; you'd still add each episode's actual video source by hand afterward, or through the TV Bulk Importer if you have the files.

Ratings

Once a title carries a TheMovieDB or IMDb id, these dynamic-only jobs fetch a score for it:

Trailers

youtube and episode_youtube jobs search for a title's trailer on YouTube and attach it. Choose how far to go on the same settings screen: keep just the YouTube id, download the video and keep the id too, or download and drop the id entirely.

Subtitles

Subtitle jobs (and their TV-episode equivalents) fetch subtitle files automatically instead of you uploading them by hand, one language at a time, from three providers:

• OpenSubtitles
• SubDL — capped at 30 downloads per run
• Subsource — capped at 100 downloads per run

Whatever these jobs bring in goes through the same SRT-to-VTT conversion as a subtitle you upload yourself, so a fetched subtitle plays exactly the same way. They can still be added or edited by hand at any time on the Movie/TV Subtitles screens, or contributed by a visitor with subtitle-upload permission (see Adding Movies & TV Content) — automation adds to that, it doesn't replace it.

Credentials

Every key and toggle above lives on one settings screen per medium: Admin area → Movies → Automation and Admin area → TV → Automation.

Getting each credential

Monitoring your cronjobs

Every run, of every job, is logged to one shared screen: Admin area → Settings → Cronjob → Run logs. Each row shows the job, its status — Failed, Running, Finished or Skipped — and a start/end time; filter by Type to see one job's history on its own. A Logs button on each row opens the step-by-step detail lines recorded during that run, which is where you'll see individual lookups and the exact point something failed.

A run that hangs — usually on a slow external API — holds its lock for up to six hours before RamTV considers it stuck and lets the schedule move on without it. If a job's runs are consistently taking that long, lower its Item limit rather than waiting it out. You can also restrict which days of the week a job is allowed to run, on Settings → Cronjob → Setting, the same way for every job on the platform, not just automation ones.

Optional: sourcing from torrents

If the separate torrent-automation add-on is installed, it adds a further set of jobs to the same cronjob screens for both movies and TV episodes. Instead of fetching metadata, these search torrent indexes for a title, score the candidates they find by quality and seed count, and can hand the best match to a Transmission download client running on your server. Once the download finishes, the resulting file is registered as a normal playable source on that movie or episode, exactly as if you had uploaded it yourself.

About the scrapers behind some of these jobs

A few of the integrations above don't call an official, documented API at all — the IMDb rating job, the YouTube trailer fallback, and the Rotten Tomatoes, Metacritic and Letterboxd rating jobs can read data directly out of the provider's own web pages when clean API access isn't available. That's a workaround for a limit or a paywall the provider put there on purpose, and doing it generally sits outside — or against — that provider's terms of service, regardless of what the code makes technically possible. Treat any scraper-based integration as a tool for testing, research and personal or local development, not for a public production site. Wherever a provider above offers real API access — TheMovieDB, YouTube, OpenSubtitles, SubDL, Subsource, MDBList, OMDb, Trakt — use it with your own credentials and read its terms. That's always the safer, more reliable path, and it's what every job in this article prefers by default.

Limitations, in one place

• New content from any job — a seeded title, a whole season TMDB built for you — goes live immediately. There's no review queue anywhere in automation
• Only TheMovieDB jobs can seed brand-new titles (Static IDs / Dynamic); every other job needs a TheMovieDB or IMDb id already on the row
• Filmography limit (default 60) caps how much of a person's back-catalogue a person_tmdb run pulls in one go
• SubDL caps at 30 subtitle downloads per run, Subsource at 100
• imdbdata is licensed for non-commercial use; MDBList's terms are silent on API/commercial use; OMDb's data is CC BY-NC 4.0 (non-commercial only) — read all three before relying on them for a commercial deployment
• YouTube trailer fetching is limited by your own API quota — add more keys if you hit it
• Letterboxd automation is movie-only, and depends on a Letterboxd public API that Letterboxd itself still calls "coming soon"
• Scraper-based jobs (IMDb, the YouTube fallback, Rotten Tomatoes, Metacritic, Letterboxd) and the optional torrent add-on carry real legal exposure — research/personal use only, never a public production site
• Every job shares a 6-hour stale-lock timeout, and can be restricted to specific days of the week
• Nothing above runs at all without an OS-level cron calling RamTV's scheduler