Metadata-Version: 2.4
Name: objectionengine2
Version: 1.0.2
Summary: Independent continuation of Objection Engine for rendering Ace Attorney scenes
Author: Luis Mayo Valbuena, Malcolm Anderson
Author-email: Luis Mayo Valbuena <luismayovalbuena@outlook.es>, Malcolm Anderson <malcolminyo@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: pillow>=10.4,<13
Requires-Dist: pydub>=0.25.1,<0.26
Requires-Dist: audioop-lts>=0.2.2,<0.3 ; python_full_version >= '3.13'
Requires-Dist: ffmpeg-python>=0.2,<0.3
Requires-Dist: spacy>=3.8.16,<3.9
Requires-Dist: opencv-python-headless>=4.14,<5
Requires-Dist: fonttools>=4.60,<5
Requires-Dist: numpy>=2.2,<3
Requires-Dist: rich>=14,<16
Requires-Dist: requests>=2.32,<3
Requires-Dist: platformdirs>=4.4,<5
Requires-Dist: toml>=0.10.2,<0.11
Requires-Dist: transformers>=4.55,<6 ; extra == 'sentiment'
Requires-Dist: torch>=2.8,<3 ; extra == 'sentiment'
Requires-Dist: sentencepiece>=0.2,<0.2.2 ; extra == 'sentiment'
Requires-Dist: protobuf>=5,<7 ; extra == 'sentiment'
Requires-Python: >=3.10, <3.15
Project-URL: Original, https://github.com/LuisMayo/objection_engine
Provides-Extra: sentiment
Description-Content-Type: text/markdown

# objectionengine2

objectionengine2 converts comment chains and scripted dialogue into Ace Attorney style videos. It is an independent continuation of [Objection Engine](https://github.com/LuisMayo/objection_engine), originally created by Luis Mayo Valbuena. The original copyright and MIT license are preserved in `LICENSE`.

The distribution, repository, and Python import are all named `objectionengine2`. Update existing `objection_engine` imports when migrating scripts.

## Requirements

- Python 3.10 through 3.14
- FFmpeg and `ffprobe` on `PATH`
- The Objection Engine asset pack. The renderer downloads it on first use into
  the user cache directory selected by `platformdirs` for `objectionengine2`.
  An existing complete `./assets/` pack is copied there on first use.

## Install

From a clone, sync the locked environment with `uv`:

```bash
uv sync --python 3.14 --locked
```

The package supports Python 3.10–3.14; `.python-version` selects 3.14 by default. To enable Hugging Face sentiment, add `--extra sentiment` to the run command, for example `uv run --locked --extra sentiment python examples/example_easy.py`. For installations from PyPI, use `uv add --torch-backend cpu "objectionengine2[sentiment]"` to select CPU-only PyTorch; the CPU index setting in this checkout does not propagate to installed packages. This downloads a model on first use into the same user cache under `models/`. The base installation does not need a model. Find the cache location with `uv run python -c 'from objectionengine2.cache import cache_path; print(cache_path())'`.

## Render comments

```python
from objectionengine2.beans.comment import Comment
from objectionengine2.renderer import render_comment_list

comments = [
    Comment(user_name="Phoenix", text_content="The defense is ready."),
    Comment(user_name="Edgeworth", text_content="The prosecution is ready."),
]
render_comment_list(comments, output_filename="outputs/output.mp4")
```

Run `uv run python examples/example_easy.py` from the repository root for a complete example. Additional scene, XML, and casting examples are in `examples/`; reference documentation is in `docs/`. Pass an `output_filename` in an existing directory. Scripts with literal `assets/...` paths still need a local asset directory; generated comment dialogue uses the user cache.

## Sentiment settings

By default, dialogue uses neutral sentiment and needs no machine learning dependency. Explicit `Comment(score=...)` values still select positive or negative sprites. Set `oe_sentiment_model=hf` after installing the `sentiment` extra to use the Hugging Face model. Setting `oe_bypass_sentiment` to a nonempty value forces neutral sentiment. The former Polyglot mode is no longer supported; an unsupported `oe_sentiment_model` value raises a clear error.

Set `OE_DIRECT_H264_ENCODING=true` only if your OpenCV build provides an H.264 encoder. The default path encodes the intermediate video with OpenCV and creates the final H.264/AAC MP4 with FFmpeg.

## Container (Podman)

The Docker image uses Python 3.14 and includes FFmpeg. Build and run the included example from the repository root:

```bash
podman build -t objectionengine2 .
podman volume create objectionengine2-cache
podman run --rm \
  --mount type=volume,src=objectionengine2-cache,dst=/root/.cache/objectionengine2 \
  --mount type=bind,src="$(pwd)/outputs",dst=/app/outputs \
  objectionengine2
```

The result is `outputs/output.mp4`. Ensure `outputs/` exists before running;
the image saves downloaded assets and models in the mounted cache volume.
To run your own script, mount it at `/app/render.py` and add `render.py` after
the image name. Have the script write into `outputs/`.

## Tests

`uv sync --locked` installs the default `dev` group, including pytest. Run `uv run --locked pytest -q` for offline tests. They generate their own small media inputs and require FFmpeg and `ffprobe` but do not download assets or models.

For a complete courtroom smoke test, run `uv run --locked pytest -q -m asset_integration`. The test calls `ensure_assets_are_available()` from `objectionengine2.utils` first, which populates the platform cache if needed. Keep that cache to avoid downloading the pack again.

## Contributing

Changes and fixes are welcome. Please run the offline suite before opening a pull request.
