> This page is for NVIDIA LipSync on Holoscan for Media, version 1.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.0.0 (Latest) (default): https://docs.nvidia.com/nim/maxine/lipsync-h4m/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.

# Operator Configuration

This page covers Helm values for the `nvidia-lipsync-h4m-operator` chart (controller pod) and fields for the `NvidiaLipsyncMediaFunction` custom resource (LipSync NIM workload).

Pipeline tuning semantics on the custom resource match the [Pipeline Configuration](/nim/maxine/lipsync-h4m/configuration/pipeline) Helm keys.

---

## Operator Helm Chart (nvidia-lipsync-h4m-operator)

Values for the operator controller pod (not the NIM Deployment).

| Configuration | Helm Key | Comment |
|---------------|----------|---------|
| Operator image | `image.repository`, `image.tag`, `image.pullPolicy` | Default: repo `nvcr.io/nim/nvidia/lipsync-h4m-operator`, tag `1.0.0`, pull `Always`. |
| Pull secrets | `imagePullSecrets` | Default: `[{name: ngc-secret-key}]`. |
| Default NIM image for operands | `mediaFunctionImage` | Single fully-qualified image reference (for example, `nvcr.io/nim/nvidia/lipsync-h4m-nim:1.0.0`). Passed to the manager as `MEDIA_FUNCTION_IMAGE`. |
| Default NIM scheduler | `defaultSchedulerName` | Default: `default-scheduler`: used when the CR omits `spec.parameters.schedulerName`. For NUMA and `topo-aware-scheduler`, see [Scheduler Requirements for NUMA-aware Clusters](/nim/maxine/lipsync-h4m/getting-started#scheduler-requirements-for-numa-aware-clusters). |
| Leader election | `leaderElection` | Default: `true`. |
| Operator pod resources | `resources.*` | Default: limits `500m` CPU / `128Mi` memory; requests `10m` CPU / `64Mi` memory. |


<Warning>
The media function is configured when the operator is installed, so `NvidiaLipsyncMediaFunction` instances managed by an operator use the same validated operator and media-function image combination. This ensures the operator and workload are always supported together and avoids compatibility issues.

As a result, CRs managed by an operator share the chart-level `mediaFunctionImage` and `imagePullSecrets` configured at install time. To run multiple custom resources with different NIM image tags, deploy multiple operators, each configured with its own `mediaFunctionImage`.
</Warning>
---

## Custom Resource (NvidiaLipsyncMediaFunction)

Full YAML example: Example Manifest in [Kubernetes Operator Chart](/nim/maxine/lipsync-h4m/installation/lipsync-h4m-operator).

### Scheduling and Cluster

| Configuration | CR Path | Comment |
|---------------|---------|---------|
| Node selector | `spec.parameters.nodeSelector` | Kubernetes node labels (for example, `kubernetes.io/hostname`). |
| Pod scheduler | `spec.parameters.schedulerName` | Optional. Kubernetes `schedulerName` for the LipSync NIM operand `Pod` (for example, `default-scheduler` or `topo-aware-scheduler`). |

### Parameters: Network, Resources, Secrets, Security, Storage

| Configuration | CR Path | Comment |
|---------------|---------|---------|
| High-speed networks | `spec.parameters.highSpeedNetwork` | Default name: `media-a-tx-net`; for Multus, list of `{name, ip?}`. |
| NGC model download | `spec.parameters.ngcApiKeySecret` | Model download `Secret`: `name`, `key`; default key: `NGC_API_KEY`. |
| Model cache / logs | `spec.parameters.nimModelCache`, `spec.parameters.serverLogs` | Fields: `enabled`, `claimName`, `size`, `storageClassName`; refer to [Advanced Usage](/nim/maxine/lipsync-h4m/advanced-usage#persistent-storage). |
| Security context | `spec.parameters.securityContext` | Example: `runAsUser: 1000`, capabilities for Rivermax and RTP; refer to [Getting Started](/nim/maxine/lipsync-h4m/getting-started). |
| NMOS metadata | `spec.parameters.label`, `spec.parameters.description` | NMOS IS-04 registration strings. |

### Parameters: CR

| Configuration | CR Path (`spec.parameters.*`) | Environment Variable (on NIM Pod) | Comment |
|---------------|------------------------------|----------------------------------|---------|
| Logging level | `loggingLevel` | `LIPSYNC_LOGGING_LEVEL` | Range: `0`–`4`; `0` FATAL, `1` ERROR, `2` WARNING, `3` INFO (default), `4` DEBUG. |
| Model head movement speed | `modelHeadMovementSpeed` | `LIPSYNC_MODEL_HEAD_MOVEMENT_SPEED` | Range: `0`…`100`; default: `0`. |
| NIM process enable | `nim.enabled` | `NIM_ENABLED` | Accepts `0` or `1`; default: `1`. |
| Input ancillary data enable (optional) | `inputAncillaryDataEnabled` | `LIPSYNC_INPUT_ANCILLARY_DATA_ENABLED` | `true` or `false`; default: `false`. Use with `spec.inputs.ancillary_data_input`. |

### Inputs and Outputs

| Area | CR Path | Comment |
|------|---------|---------|
| Video in | `spec.inputs.video_input` | Uses `control`, `transport`, and `format.video`. |
| Audio in | `spec.inputs.audio_input` | Single audio stream. |
| Ancillary in (optional) | `spec.inputs.ancillary_data_input` | Optional ancillary/metadata input (`control`, `transport`, `format.data`). |
| Video out | `spec.outputs.video_output` | Lip-synced program video. |

#### Video Format Subfields

These subfields apply to video input and video output.

| Field | Example Value | Comment |
|-------|---------------|---------|
| `media_type` | `video/raw` | Fixed for uncompressed ST 2110-20. |
| `frame_width` | `1920` | Must match NIM `video.width`. |
| `frame_height` | `1080` | Must match NIM `video.height`. |
| `frame_rate` | `"30"` | [Allowed values](#video-frame-rate) (CRD admission); set the *same* value on input and output video. |
| `interlace_mode` | `progressive` | CRD `enum`: `progressive`, `interlaced_tff`, `interlaced_bff`, `interlaced_psf`; refer to the `kubectl explain` paths in [CR Schema Reference](#cr-schema-reference). |
| `component_depth` | `10` | CRD `enum`: `8`, `10`, `12`; must match NIM `video.componentDepth`. |
| `color_sampling` | `YCbCr-4:2:2` | |
| `colorspace` | `BT709` | |
| `transfer_characteristic` | `SDR` | |

#### Video Frame Rate

`spec.inputs.video_input.format.video.frame_rate` and `spec.outputs.video_output.format.video.frame_rate` must be identical. Invalid values are rejected when the CR is applied.

Supported values: `"24"`, `"25"`, `"30000/1001"`, `"30"`, `"50"`, `"60000/1001"`, `"60"`

Use a plain integer string for whole rates (for example `"30"`) and a `numerator/denominator` string for fractional rates (`"30000/1001"`, `"60000/1001"`). Quote values in YAML so that fractions are not parsed as numbers.

#### Audio Format Subfields

These subfields apply to audio input streams.

| Field | Example Value | Comment |
|-------|---------------|---------|
| `sample_rate` | `48000` | Must match NIM `audio.samplingRate`. |
| `channel_count` | `1` | Mono per stream; must match NIM `audio.numChannels`. |
| `sample_depth` | `24` | Bits; corresponds to PCM L24. |
| `media_type` | `audio/L24` | Fixed for ST 2110-30 mono L24. |

### CR Schema Reference

With the `nvidialipsyncmediafunctions.nvidia.com` CRD installed, inspect field types and OpenAPI details from the cluster:

```bash
kubectl explain nvidialipsyncmediafunctions.nvidia.com --recursive
kubectl explain nvidialipsyncmediafunctions.nvidia.com.spec
kubectl explain nvidialipsyncmediafunctions.nvidia.com.spec.inputs.video_input.format.video
kubectl explain nvidialipsyncmediafunctions.nvidia.com.spec.outputs.video_output.format.video
```

Some validation rules might not appear in `kubectl explain` output but are still enforced when the CR is applied.

### Status Conditions (`status.conditions`)

#### Status Overview

The operator reports health using Kubernetes conditions in `status.conditions` (`type`, `status`, `reason`, `message`).

A media function is considered healthy and ready when the following are all `True`:

- `Provisioned`: Deployment and pod are running.
- `Registered`: Successfully registered with NMOS/SDP.
- `Configured`: Required configuration has been applied.

#### Important Statuses

| Status | What It Means |
|--------|----------------|
| `Provisioned` | App deployment is running. |
| `Registered` | Registration succeeded. |
| `Configured` | Configuration applied successfully. |
| `Connected` | Connections are established. |
| `Active` | Reserved for future media-flow status. |
| `Degraded` | Reserved for future health reporting. |

#### When to Alert

Alert if any of the following stay `False`:

- `Provisioned`
- `Registered`
- `Configured`

Most important failure `reason` values:

- `DeploymentNotAvailable`
- `NmosQueryFailed`

`Connected` `False` is usually informational or transient and can occur when connections are still being established.

Ignore `Active` and `Degraded` for now.

#### Check Status

Use the custom resource `metadata.name` (not a Pod name).

```bash
kubectl get nvidialipsyncmediafunction <cr-name> \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\n"}{end}'
```

---

## See Also

- [Configuration Reference](/nim/maxine/lipsync-h4m/configuration)
- [Kubernetes Operator Installation](/nim/maxine/lipsync-h4m/installation/lipsync-h4m-operator)
- [Pipeline Configuration](/nim/maxine/lipsync-h4m/configuration/pipeline): Pipeline tuning Helm key equivalents.