> This page is for NVIDIA Synthetic Video Detector NIM, version 2.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 2.0.0 (Latest) (default): https://docs.nvidia.com/nim/maxine/synthetic-video-detector/2.0.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/maxine/synthetic-video-detector/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/maxine/llms.txt.

# Basic Inference

This guide demonstrates how to perform basic inference with the Synthetic Video Detector NIM over gRPC.

## Prerequisites

1. Ensure that the Synthetic Video Detector NIM container is running. For container launch instructions, refer to [Getting Started](/nim/maxine/synthetic-video-detector/getting-started).

2. Verify that the service is accessible by performing a health check on the gRPC endpoint.

   - Install `grpcurl` from [github.com/fullstorydev/grpcurl/releases](https://github.com/fullstorydev/grpcurl/releases).

      Example commands to run on Ubuntu:

      ```bash
      wget https://github.com/fullstorydev/grpcurl/releases/download/v1.9.1/grpcurl_1.9.1_linux_amd64.deb
      sudo dpkg -i grpcurl_1.9.1_linux_amd64.deb
      ```

   - Download the health checking proto:

      ```bash
      wget https://raw.githubusercontent.com/grpc/grpc-proto/master/grpc/health/v1/health.proto
      ```

   - Run the health check:

      ```bash
      grpcurl --plaintext --proto health.proto localhost:8001 grpc.health.v1.Health/Check
      ```

     If the service is ready, you get a response similar to the following:

      ```bash
      { "status": "SERVING" }
      ```
   <Note>
   For using grpcurl with an SSL-enabled server, avoid using the `--plaintext` argument, and use `--cacert` with a CA certificate, `--key` with a private key, or `--cert` with a certificate file. For more details, refer to `grpcurl --help`.
   </Note>

3. Download the Synthetic Video Detector Python client code by cloning the Clients repository ([NVIDIA-Maxine/nim-clients](https://github.com/NVIDIA-Maxine/nim-clients)):

   ```bash
   git clone https://github.com/NVIDIA-Maxine/nim-clients.git

   # Go to the 'synthetic-video-detector' folder

   cd nim-clients/synthetic-video-detector/ 
   ```

4. Install the required dependencies:

   ```bash
   sudo apt-get install python3-pip
   pip install -r requirements.txt
   ```   


##  Compile the Protos (Optional)

If you want to use the client code provided in the Clients repository ([NVIDIA-Maxine/nim-clients](https://github.com/NVIDIA-Maxine/nim-clients)), you can skip this step.

The proto files are available in the `synthetic-video-detector/protos` folder. The v2 API used by this NIM is defined under `protos/proto/nvidia/ai4m/`; the earlier v1 API is kept alongside it under `protos/proto/nvidia/maxine/`. You can compile them to generate client interfaces in your preferred programming language. For more details, refer to [Supported languages](https://grpc.io/docs/languages/) in the gRPC documentation.

The following is an example of how to compile the protos for Python on Linux and Windows. The compile script builds both API generations in a single pass.
The `grpcio` version needed for compilation can be referred from `requirements.txt`

To compile protos on Linux:

```bash
# Go to synthetic-video-detector/protos/linux folder
cd synthetic-video-detector/protos/linux

chmod +x compile_protos.sh
./compile_protos.sh
```

To compile protos on Windows:

```bash
# Go to synthetic-video-detector/protos/windows folder
cd synthetic-video-detector/protos/windows

./compile_protos.bat
```

The generated Python stubs are written to `synthetic-video-detector/interfaces`, mirroring the proto packages. The v2 stubs are imported as follows:

```python
from nvidia.ai4m.syntheticvideodetector.v1 import syntheticvideodetector_pb2
from nvidia.ai4m.ingest.v1 import presigned_url_pb2
```

## Input and Output

The Synthetic Video Detector NIM takes a single input video and returns an overall synthetic probability, with optional per-frame results for analysis. Audio tracks, if present, are ignored.

The following table lists the container and video codec combinations supported by this NIM. The runtime demuxes the container, and NVDEC decodes the video on supported GPUs.

| Container | File extensions | Video codecs |
| --- | --- | --- |
| MP4 / QuickTime | `.mp4`, `.mov`, `.m4v` | H.264/AVC, H.265/HEVC, AV1 |
| Matroska | `.mkv` | H.264/AVC, H.265/HEVC, AV1, VP8, VP9 |
| WebM | `.webm` | VP8, VP9 |

Container support is provided by the runtime demuxer. Hardware decoding support for a codec, profile, pixel format, chroma subsampling, bit depth, and resolution depends on the exact GPU. For per-GPU capabilities, refer to the [NVIDIA Video Encode and Decode GPU Support Matrix](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new).

The **maximum input resolution** also depends on the codec and exact GPU. For the per-architecture minimum and maximum resolutions, refer to the [NVDEC Video Decoder API Programming Guide](https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/nvdec-video-decoder-api-prog-guide/index.html). The performance measurements cover inputs up to 4K; refer to [Performance Results](/nim/maxine/synthetic-video-detector/performance-results).

<Note>
The reference evaluation uses H.264/AVC-encoded videos. Detection accuracy can vary with codec, video quality, compression, re-encoding, and source model. Refer to [Reference Accuracy](/nim/maxine/synthetic-video-detector/advanced-usage#reference-accuracy).
</Note>

### Inference Workflows

The NIM automatically selects the inference workflow based on the input; you do not set it explicitly.

- **Streaming inference** is used only for **streamable (fast-start) H.264 MP4** input, that is, files whose `moov` atom is placed before the media data (for example, encoded with `ffmpeg -movflags +faststart`). In this mode, decoding and inference overlap with the byte upload for lower latency.
- **Transactional inference** is used for **all other inputs**, including non-fast-start MP4 files, H.265, AV1, VP8, and VP9 streams, and Matroska/WebM containers. The input is fully received before decoding begins.
- **Pre-signed URL (S3) ingest always uses the transactional workflow.** For details, refer to [Pre-signed URL Ingest](/nim/maxine/synthetic-video-detector/advanced-usage#pre-signed-url-ingest).

The following table summarizes the two workflows:

| Aspect | Streaming | Transactional |
| --- | --- | --- |
| Applies to | Streamable (fast-start) H.264 MP4 | All other inputs (non-fast-start MP4; H.265, AV1, VP8, VP9; MKV/WebM; and pre-signed URL ingest) |
| Data handling | Decoding and inference overlap with the byte upload | The full input is received before decoding begins |
| Latency | Lower — results stream back as frames are processed | Higher — processing starts after the upload completes |

Streaming mode applies only to fast-start H.264 MP4 input. To convert a regular MP4 to fast-start (which moves the `moov` atom to the front of the file), use FFmpeg:

```bash
ffmpeg -i input.mp4 -c copy -movflags +faststart output_streamable.mp4
```

Then pass the streamable file with `--video-input`. When the input is not fast-start H.264 MP4, the NIM automatically falls back to the transactional workflow.

## Running Inference

To run the Synthetic Video Detector NIM, run the Synthetic Video Detector sample client without any additional flags:

Go to the v2 `scripts` directory:

```bash
cd scripts/v2
```

Send a gRPC request:

```bash
python synthetic-video-detector.py --target <server_ip:port> \
   --video-input <input file path> \
   --save-csv
```

<Note>
The first inference is not indicative of the model's actual performance because it includes the time taken by the inference server to load the models in addition to the time required to process the inference request. 
</Note>

### Pre-signed URL (S3) Ingest

Instead of streaming the video bytes, you can point the NIM at a video that already lives in object storage (for example, an AWS S3 bucket) by sending a single **pre-signed HTTPS URL**. The NIM validates the URL, downloads the object itself, and runs the same detection pipeline. For a description of the ingest pipeline, the security model, and the tuning environment variables, refer to [Pre-signed URL Ingest](/nim/maxine/synthetic-video-detector/advanced-usage#pre-signed-url-ingest).

The same `synthetic-video-detector.py` client handles this mode: pass `--presigned-url` instead of `--video-input` (the two are mutually exclusive). The client then sends a single `PresignedUrl` request rather than streaming bytes:

```bash
python synthetic-video-detector.py \
   --target <server_ip:port> \
   --presigned-url "<pre-signed-https-url>" \
   --presigned-url-provider s3 \
   --presigned-checksum-type sha256 \
   --presigned-checksum <expected-sha256-hex> \
   --save-csv
```

To skip server-side checksum verification for a basic verification test against a generic URL, disable verification instead of supplying a checksum:

```bash
python synthetic-video-detector.py \
   --target <server_ip:port> \
   --presigned-url "<https-url>" \
   --presigned-content-type video/mp4 \
   --presigned-no-verify-checksum
```

<Note>
Use `--presigned-url-provider s3` only for AWS S3 pre-signed URLs; it enables server-side AWS SigV4 URL-shape validation. For other HTTPS object stores, add the hostname to `NV_AI4M_PRESIGNED_ALLOWED_HOSTS` and omit `--presigned-url-provider s3`.
</Note>

<Note>
With checksum verification enabled (the default), you **must** pass `--presigned-checksum` together with `--presigned-checksum-type`, or the server rejects the request. Use `--presigned-no-verify-checksum` to opt out. Supported checksum algorithms are `md5`, `sha256`, and `sha512`.
</Note>

To view details of command-line arguments, run the following command:

```bash
python synthetic-video-detector.py -h
```
You get a response similar to the following. All parameters are optional.

```text
options:
  -h, --help                        show this help message and exit
  --ssl-mode {DISABLED,MTLS,TLS}    Flag to set SSL mode, default is DISABLED (default: DISABLED)
  --ssl-key SSL_KEY                 The path to ssl private key. (default: ../ssl_key/ssl_key_client.pem)
  --ssl-cert SSL_CERT               The path to ssl certificate chain. (default: ../ssl_key/ssl_cert_client.pem)
  --ssl-root-cert SSL_ROOT_CERT     The path to ssl root certificate. (default: ../ssl_key/ssl_ca_cert.pem)
  --target TARGET                   IP:port of gRPC service, when hosted locally. Use grpc.nvcf.nvidia.com:443 when hosted on NVCF. (default: 127.0.0.1:8001)
  --video-input VIDEO_INPUT         Path to the input video file to analyze (supports MP4/MOV/M4V, MKV, and WebM). Defaults to ../../assets/fake_sample_video.mp4 when neither --video-input nor --presigned-url is provided. Mutually exclusive with --presigned-url. (default: None)
  --save-csv [FILENAME]             Save results to CSV. Optionally specify a custom filename, otherwise uses the input video's (or URL's) base name (e.g., video.csv) (default: False)

pre-signed URL ingest (S3):
  --presigned-url PRESIGNED_URL     Pre-signed (or direct) HTTPS URL to the input object. When set, the client sends a single pre-signed URL request instead of streaming a local file. Mutually exclusive with --video-input. (default: None)
  --presigned-url-provider {unspecified,s3}
                                    Provider hint; 's3' enables SigV4 URL-shape validation server-side. (default: unspecified)
  --presigned-checksum-type {md5,sha256,sha512}
                                    Checksum algorithm for --presigned-checksum. (default: sha256)
  --presigned-checksum PRESIGNED_CHECKSUM
                                    Expected lowercase hex checksum digest of the downloaded file. (default: None)
  --presigned-no-verify-checksum    Set verify_checksum=false so the server skips checksum verification (otherwise the server requires a checksum). (default: False)
  --presigned-expected-size PRESIGNED_EXPECTED_SIZE
                                    Expected Content-Length in bytes (verified by the server). (default: None)
  --presigned-content-type PRESIGNED_CONTENT_TYPE
                                    Expected Content-Type, e.g. video/mp4 (verified by the server). (default: None)
  --presigned-expires-at-unix-ms PRESIGNED_EXPIRES_AT_UNIX_MS
                                    Client assertion of URL expiry, in Unix epoch milliseconds. (default: None)
```

### Python Notebook

For an interactive experience and to explore all feature parameters, we provide a comprehensive Python notebook that demonstrates the Synthetic Video Detector service capabilities.

The Python notebook is located at `notebook/v2/synthetic_video_detector_notebook.ipynb` in the `synthetic-video-detector` client folder.