Metadata-Version: 2.4
Name: reavideo-breakdown
Version: 1.0.0
Summary: Parse a plain-text shot list into structured shots, timings and cut statistics.
Author: reavideo
License: MIT
Project-URL: Homepage, https://reavideo.pro/
Project-URL: Source, https://github.com/youram470-art/reavideo-breakdown
Keywords: video,shot list,storyboard,editing,timecode
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# reavideo-breakdown

Parse a plain-text shot list into structured shots, timings and cut statistics.

A shot list is the cheapest artifact of video production: one line per cut,
usually something like `00:04  wide shot, empty street, slow push in`. This
library turns that text into data you can sort, validate and diff, which is
what you need when a finished video has to be broken back down into its
component shots.

No dependencies outside the standard library.

## Install

```bash
pip install reavideo-breakdown
```

## Usage

```python
from reavideo_breakdown import parse_shotlist, summarize, format_timecode

text = """
00:00-00:04   wide shot, empty street, slow push in
00:04-00:07   close up, hands tying a knot
00:07-00:12   3.5s  drone pull back over the harbour
"""

shots = parse_shotlist(text)
for shot in shots:
    print(shot["index"], format_timecode(shot["start"]), shot["description"])

summarize(shots)
```

`parse_shotlist` returns a list of dicts:

| key | meaning |
| --- | --- |
| `index` | 1-based position in the list |
| `start` | start time in seconds |
| `end` | end time in seconds, or `None` when the line only marks a cut |
| `duration` | `end - start`, or `None` |
| `description` | the line with its timecode and optional `3.5s` marker removed |
| `line` | the original line, so errors can be reported next to the source |

`summarize` adds the numbers editors ask for first: shot count, cuts per
minute, average, longest and shortest shot.

## Timecodes

```python
from reavideo_breakdown import parse_timecode, format_timecode

parse_timecode("1:02:03")   # 3723.0
format_timecode(3723)       # '01:02:03'
```

Both `mm:ss` and `hh:mm:ss` are accepted; output switches to `hh:mm:ss` past
one hour.

## Link

Written for shot breakdown work on finished cuts; the tool this pairs with is
[Rea Video](https://reavideo.pro/), which reconstructs a shot list from a
delivered video.

## License

MIT
