Basic Inference#

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

Prerequisites#

Ensure that the Synthetic Video Detector NIM container is running. For container launch instructions, refer to Getting Started.
Verify that the service is accessible by performing a health check on the gRPC endpoint.
- Install grpcurl from github.com/fullstorydev/grpcurl/releases.
  
  Example commands to run on Ubuntu:
```
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:
```
wget https://raw.githubusercontent.com/grpc/grpc/master/src/proto/grpc/health/v1/health.proto
```
- Run the health check:
```
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:
```
{ "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.

Download the Synthetic Video Detector Python client code by cloning the Clients repository (NVIDIA-Maxine/nim-clients):

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

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

cd nim-clients/synthetic-video-detector/ 

Install the required dependencies:

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), 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 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:

# 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:

# 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:

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.

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. The performance measurements cover inputs up to 4K; refer to 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.

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.

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:

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:

cd scripts/v2

Send a gRPC request:

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.

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.

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:

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:

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

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.

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

python synthetic-video-detector.py -h

You get a response similar to the following. All parameters are optional.

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.