Metadata-Version: 2.4
Name: prproj-parser
Version: 0.1.0
Summary: Efficient parser for Adobe Premiere Pro .prproj project files
Author: catastrofia
License: MIT
Project-URL: Homepage, https://github.com/catastrofia/prproj-parser
Project-URL: Issues, https://github.com/catastrofia/prproj-parser/issues
Keywords: premiere,premiere-pro,prproj,adobe,video-editing,parser,xml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: fast
Requires-Dist: lxml>=4.9; extra == "fast"
Provides-Extra: secure
Requires-Dist: defusedxml>=0.7; extra == "secure"
Provides-Extra: all
Requires-Dist: lxml>=4.9; extra == "all"
Requires-Dist: defusedxml>=0.7; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: mypy<2.5,>=1.8; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: ruff==0.17.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# prproj-parser

A pure-Python parser for Adobe Premiere Pro `.prproj` project files. Extracts sequences, tracks, and clips (with resolved media paths, timecodes, and clip types) without needing Premiere Pro installed.

`.prproj` files store a flat, gzip-compressed XML object graph — sequences, tracks, and clips reference each other by ID rather than nesting. This library resolves that reference graph into a simple, typed object model.

## Install

```bash
pip install prproj-parser
```

Optional extras:

```bash
pip install prproj-parser[fast]    # lxml backend (faster parsing)
pip install prproj-parser[secure]  # defusedxml backend (hardened against XML entity attacks)
pip install prproj-parser[all]     # both
```

Requires Python 3.9+. No dependencies by default — falls back to the stdlib `xml.etree.ElementTree`.

Parsing is single-pass and scales linearly: an 8,000-clip project loads in ~0.2 s on a typical laptop on the default stdlib/defusedxml backends (smaller gains under the `lxml` extra; see `benchmarks/`).

## Quick start

```python
from prproj_parser import load

project = load("my_project.prproj")

for seq in project.sequences:
    print(seq.name, seq.frame_rate, seq.duration_seconds)
    for clip in seq.clips:
        print(f"  [{clip.clip_type}] {clip.name}  {clip.start_timecode}-{clip.end_timecode}")
        if clip.media:
            print(f"    media: {clip.media.best_path}")
```

For just the sequence names (near-zero memory, doesn't resolve clips):

```python
from prproj_parser import list_sequences

names = list_sequences("my_project.prproj")
```

## API

| Function / Class | Purpose |
|---|---|
| `load(file_path)` | Parse a `.prproj` file, return a fully-resolved `Project`. |
| `list_sequences(file_path)` | Ultra-lightweight: just sequence names. |
| `Project` | `.sequences`, `.sequence_names`, `.get_sequence(name)` |
| `Sequence` | `.clips`, `.video_clips`, `.audio_clips`, `.tracks`, `.frame_rate`, `.duration_seconds` |
| `Track` | `.index`, `.track_type`, `.clips` |
| `Clip` | `.name`, `.start_timecode`/`.end_timecode`, `.start_seconds`/`.end_seconds`, `.duration_seconds`, `.clip_type`, `.speed_percent`, `.media`, `.is_nested_sequence` |
| `MediaInfo` | `.best_path`, `.file_path`, `.actual_path`, `.relative_path`, `.title` |

`clip_type` is one of `"Video"`, `"Audio"`, `"Image"`, `"Graphic"`, `"Premiere element"` (adjustment layers, color mattes, black video, bars & tone — no real underlying media file), or `"Unknown"`.

`speed_percent` is `100.0` for normal speed, `200.0` for 2x, `50.0` for half speed, etc.

Both `.prproj` files that are gzip-compressed (the common case) and files that are plain UTF-8 XML (also produced by Premiere Pro) are supported transparently.

See the module docstrings (`help(prproj_parser)`) for full API details — the package ships with type hints (`py.typed`).

## Known limitations

- **Nested/multicam sequences are not flattened.** A sequence nested inside another timeline is detected (`clip.is_nested_sequence == True`) but its own clips are not recursively resolved. Tracked in [#1](https://github.com/catastrofia/prproj-parser/issues/1).
- **Speed ramps / time remapping** (as opposed to a single constant speed) report the clip's base `PlaybackSpeed` value; keyframed speed changes over the clip's duration are not modeled.
- Verified against Premiere Pro project files from versions 2023–2026 (`PremiereData Version="3"`). Older/newer formats are untested.

## `.prproj` format notes

Contributor/reference docs live in [docs/prproj-format/](docs/prproj-format/00-overview.md). They are unofficial research notes based on observed project files, not an Adobe-authoritative spec.

## Development

```bash
python -m pip install -e ".[dev,all]"
ruff check .
ruff format --check .
mypy src
pytest
python -m build
python -m twine check dist/*
```

## License

MIT
