# Movie & Series Marathon Planner

> Plan a binge: when each movie or episode starts and ends, total days, and a calendar. Add movies (runtime) and series (episodes × minutes × seasons), your breaks, when you start and how many hours a day you want to watch. The planner schedules every movie and episode, tells you how many days the marathon takes and whether you finish by a date, and exports the viewing sessions as an .ics calendar.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://runtimemarathonplanner.usefulweb.site/ (interactive tool at https://runtimemarathonplanner.usefulweb.site/tool)
- JSON API: POST https://runtimemarathonplanner.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://runtimemarathonplanner.usefulweb.site/api/v1/tool)
- OpenAPI: https://runtimemarathonplanner.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://runtimemarathonplanner.usefulweb.site/mcp - tool `runtime_marathon_planner`

## Inputs
- titles (table, required): Movies and series - Movie: runtime in minutes. Series: minutes per episode, episodes per season and seasons.
- start (datetime, required): Start - When the marathon begins (local time).
- dailyStart (time): On the following days, start at
- maxHoursPerDay (number): Maximum viewing per day - Watching time only; breaks come on top.
- breakMinutes (number): Break between episodes
- titleBreakMinutes (number): Break between titles
- allowSplit (boolean): Allow pausing a movie or episode and continuing the next day
- finishBy (date): Finish by - Optional: checks whether you make it by the end of this day.

## Method
- Each movie is one item; each series becomes episodes × seasons items of the given length.
- Items are watched in the order entered. Within a day, a break follows each item (the episode break inside a title, the title break between titles); breaks do not count towards the daily maximum.
- If the next item would push the day over the maximum viewing time, it moves to the next day at the daily start time. With pausing allowed, an item is split instead when at least 15 minutes fit into the day.
- An item longer than the daily maximum is scheduled in one piece (with a warning) unless pausing is allowed.
- A viewing session belongs to the day it starts, even if it runs past midnight. Times are local wall-clock times without a time zone; the .ics file uses floating times (RFC 5545), so calendars show them at the same clock time wherever you are.
- Finish-by check: the last item must end before midnight at the end of that date. Required hours per day = total watching time ÷ number of days from the start date to the finish-by date.