# Python binding for Rust Media Cloud AI Worker SDK

Based on [mcai_worker_sdk](https://gitlab.com/media-cloud-ai/sdks/rs_mcai_worker_sdk).

## Build

To build the rust application

```bash
cargo build
```

## Test

To run the unit tests, you must build the provided worker example (see the Build section above).

```bash
cargo test
```

## Usage

This worker uses the [PyO3 crate](https://github.com/PyO3/pyo3) to load a Python file, and to execute it.

To implement a worker, a `pyproject.toml` file must be created with metadata describing the worker.
It must at least contain both `project` and `build-system` sections.

Example: (minimal configuration)

```toml
[project]
name = "my_python_worker"
version = "1.2.3"
description = "My Python worker"
license = { text = "MIT" }

[build-system]
requires = []
```

The Python worker parameters must be into a __Python class__ as _static_ attributes.
Each parameter type must be explicitly set.

Example:

```python
import typing

class MyWorkerParameters:
    a_parameter: int
    another_parameter: typing.Optional[str] = None
```

The Python worker itself must be defined as a __Python class__ implementing some methods:

* `get_parameters_type() -> typing.Type` (_static_):
    * To retrieve the worker parameters class
* `init()` (_static_):
    * To initialize the worker process (optional)
* `process(handle_callback, parameters, job_id) -> dict` (_static_) with `parameters` instance of the worker parameter
  class:
    * To execute the worker process and return the job result.

If the `media` feature is enabled, the following function must be implemented:

* `init_process(stream_handler, format_context, parameters) -> list` (_static_) with `parameters` instance of the worker
  parameter class:
    * To initialize the media worker process and return a list of `GenericStreamDescriptor`s
* `process_frames(job_id, stream_index, frames) -> dict` (_static_):
    * To process some input audio/video frames and return the job result.
* `process_ebu_ttml_live(job_id, stream_index, ttml_contents) -> dict` (_static_):
    * To process some input EBU TTML frames and return the job result.
* `ending_process()` (_static_):
    * To end the media worker process

__NB:__ the `process(handle_callback, parameters, job_id) -> dict` function is not called when the `media` feature is
enabled.

For more details, see the provided [worker.py](worker.py) and [media_worker.py](media_worker.py) examples.

Set the `PYTHON_WORKER_FILENAME` environment variable to specify the path of your Python worker. Otherwise,
the `worker.py` file will be loaded by default.

### Running examples

#### Simple worker

```bash
RUST_LOG=debug \
SOURCE_ORDERS="examples/message.json" \
PYTHON_WORKER_FILENAME="worker.py" \
SOURCE_PATH="README.md" \
DESTINATION_PATH="README.md.out" \
cargo run
```

#### Media worker

First set the media filename:

```bash
export SOURCE_PATH="/folder/filename.ext"
```

Then run the SDK with these parameters:

```bash
RUST_LOG=debug \
SOURCE_ORDERS="examples/message.json" \
PYTHON_WORKER_FILENAME="media_worker.py" \
DESTINATION_PATH="results.json" \
cargo run --features media
```