Advanced Usage
Model Caching
When the container launches for the first time, it downloads the required models from NGC. To avoid downloading the models on subsequent runs, you can cache them locally by using a cache directory:
For more information about MANIFEST_PROFILE_ID, refer to Model Manifest Profiles.
SSL enablement
NVIDIA AI for Media Relighting provides an SSL mode to ensure secure communication between clients and the server by encrypting data in transit. To enable SSL, you must provide the path to the SSL certificate and key files in the container. The following example shows how to do this:
NIM_SSL_MODE can be set to mtls, tls, or disabled. If set to mtls, the container uses mutual TLS authentication. If set to tls, the container uses TLS authentication.
For more information, refer to Environment Variables.
Be sure to verify the permissions of the SSL certificate and key files on the host machine. The container cannot access the files if they are not readable by the user running the container.
NIM Service Configuration Parameters via Client
Use the following options to configure each request to Relighting.
HDR/Illumination Options
-
hdri_preset_id: Specifies a built-in HDR preset to create one of several lighting moods. Mutually exclusive withhdri_image_provided.0(Lounge): Lounge environment.1(Cobblestone Street Night): Cobblestone street at night.2(Glasshouse Interior): Glasshouse interior.3(Little Paris Eiffel Tower): Little Paris Eiffel Tower.4(Wooden Studio): Wooden studio environment.
The following example uses the sample Python client with the Little Paris Eiffel Tower HDR preset:
-
hdri_image_provided: When set totrue, indicates that a custom HDR environment map is sent inline asImageData. Custom HDR images take priority over preset IDs.The following example uses the sample Python client with a custom HDR file:
-
angle_pan_radians: Pan angle for rotating the HDR environment (in radians via API, degrees via CLI). Default is -90 degrees. -
angle_v_fov_radians: Vertical field of view for HDR projection (in radians via API, degrees via CLI). Default is 60 degrees.
Autorotate Options
-
autorotate: Enable automatic rotation of the HDR environment during video playback for dynamic lighting effects. -
rotation_rate: Speed of rotation in degrees per second (default: 20). Only applies when autorotate is enabled.The following example enables autorotate with a custom rotation speed:
Background Source Options
-
background_source: Selects which background source to use. Combine withblur_strengthfor blurred variants.0(UNSPECIFIED): Use source video frame as background (default).1(FROM_IMAGE): Use custom background image uploaded viaImageData.2(FROM_HDR): Use HDR environment map as background.
The following example uses the sample Python client with blurred source background:
-
background_image_type: When usingbackground_source = 1(FROM_IMAGE), a custom background image is sent inline asImageDatawithIMAGE_TYPE_BACKGROUND. Supports PNG, JPG, and HDR formats. -
background_color: Solid background color specified as ‘gray’ or hex value like ‘0x808080’. Used whenbackground_sourceisFROM_IMAGEand no image is uploaded.
Effect Parameters
-
foreground_gain: Controls the strength of relighting applied to the foreground subject (0.0–2.0, default: 1.0). Higher values produce more intense relighting effects. -
background_gain: Controls the strength of relighting applied to the background (0.0–2.0, default: 1.0). -
blur_strength: Controls background blur intensity (0.0–1.0, default: 0.0). Can be combined with anybackground_sourceto produce blurred variants. -
specular: Controls specular highlight intensity (0.0–2.0, default: 0.0). Higher values produce more prominent highlights on reflective surfaces.
Encoding Options
To configure the encoding quality of the output video, use the output_video_encoding parameter. The encoding uses a VideoEncoding message with three mutually exclusive modes: lossy, lossless, or custom.
-
Bitrate control (lossy mode): Target bitrate is specified in megabits per second (
bitrate_mbps). Use0for auto, which selects the server default 10 Mbps (fixed; not tied to output resolution). Higher values improve quality and increase output size; lower values save bandwidth at the cost of quality.-
In the configuration message, set
output_video_encoding.lossy.bitrate_mbpsto the desired Mbps or0for auto (10 Mbps). -
The sample Python CLI uses
--bitratein bps (rounded to Mbps for the proto); default matches 10 Mbps (10,000,000 bps). Example explicit bitrate:
-
-
IDR interval control:
idr_intervalis the spacing between IDR frames in frames (not seconds). The sample CLI defaults to 8 frames and always sends a value to the server. Values must be ≥ 1 (0is invalid). Sample CLI override: -
Lossless mode: Encodes the output video without compression. To enable lossless mode via the sample client, use the
--losslessflag: -
Custom encoding parameters: Provides fine-grained control for expert users via JSON configuration. These parameters configure properties of the DeepStream H264 encoder.
To specify custom encoding parameters, use the
--custom-encoding-paramsoption:Custom encoding parameters override standard bitrate and IDR interval settings. Use with caution because incorrect values can affect output quality or encoding stability.
The following example shows how to set the configuration parameters while sending an inference request from a Python client to Relighting:
For more information, refer to the NIM Clients GitHub repository: NVIDIA AI for Media NIM Clients.