# CoreMF: object tracking and MP4 transcoding

Connect decoding, an object-tracking plugin, dynamic box/text highlighting and
encoding in one graph using the API-based `runAPI` runner.

## Requirements

- A matching CoreMF runtime with runAPI, Python plugin support, usable H.264/AAC
  encoders and its runtime dependencies.
- A separately supplied compatible tracking package. Its manifest must register
  CoreAIProcessor with the `ai_processor` profile; its registry must expose the
  `object_track` algorithm. Configure its model and dependencies first, using
  that package's instructions. The model, plugin and dependency rights must
  cover the intended use/delivery.
- A short input video containing recognizable objects and new output filenames
  in a writable directory.

No model, Python AI environment or internal default tracker is supplied by this
example or included in the base commercial SDK. This is an integration recipe
for a compatible, separately selected package, not a standalone AI download.

## Run

Replace the package path and input filename. This command uses POSIX shell
quoting/line continuation; on Windows use runAPI.exe and the equivalent quoting
for your shell.

```sh
runAPI --script-plugin /absolute/path/to/tracker/plugin.json \
  -i input.mp4 -o tracked.mp4 -p objecttrack \
  -s 1280x720 -r 25 -gpl off \
  -filter-config '{"sample_every":1}' -j tracked.graph.json
```

`sample_every: 1` processes every frame reaching the AI processor. The package
supplies its own approved model configuration and supported processor parameters.
`-gpl off` restricts encoder selection; it does not change the linked runtime's
license. An allowed H.264 encoder/device must be usable on the target machine.

## Data flow and artifacts

1. CoreURLSource reads compressed video and available audio.
2. CoreDecoderFilter decodes video frames for CoreAIProcessor.
3. The processor returns frame-timestamped track events containing boxes,
   labels, confidence and track IDs. CoreMF translates them into highlight
   metadata; CoreHighlightFilter draws the returned boxes/text.
4. CoreEncoderFilter converts/encodes the annotated video to the selected output
   format. Available audio follows its decode/encode branch. CoreURLSink muxes
   the output MP4.

For the compatible AI profile, inspect:

| File                    | What to check                                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| tracked.mp4             | Actual detections produce moving boxes/text; no detections need no boxes. Check the full video, final frames and available audio/sync. |
| tracked_all_results.csv | Frame timestamps, event kinds, track IDs, confidence and bounding boxes correspond to the output.                                      |
| tracked.graph.json      | Exported source, decoder, AI, highlight, encoder, sink and audio-branch configuration.                                                 |

Detection coverage and identity stability come from the model/tracker, not from
encoding. Measure correctness, elapsed time, memory and frame latency on the
target hardware. No inference output or new model/platform qualification is
claimed by these instructions.

## Embed in an application

runAPI uses CoreMF_API.h. An application may build the graph through its public
node/link methods or import a configured Graph JSON pipeline after loading the
required plugin. Custom frame processing belongs to the plugin interface, not
an arbitrary raw-frame callback on the binary application API.