> 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.

# Getting Started

## Holoscan for Media

Platform setup, cluster prerequisites, reference applications, deployment, verification, monitoring, application development, troubleshooting, and support for Holoscan for Media are covered in the [NVIDIA Holoscan for Media](https://docs.nvidia.com/holoscan-for-media/latest/index.html) user guide.

---

## Prerequisites

Before proceeding, check the [Support Matrix](/nim/maxine/lipsync-h4m/support-matrix) to verify that the required hardware and software are available.


| Requirement                                | Details                                                                                                                                                                                         | Reference                                                                                         |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Kubernetes cluster                         | Kubernetes or Red Hat OpenShift.                                                                                                                                                                | [Support Matrix](/nim/maxine/lipsync-h4m/support-matrix)                                                               |
| OpenShift setup                            | Create the target namespace and grant SCC permissions to each service account your workloads use (often `default`). | [OpenShift Setup](#openshift-setup)                                                               |
| Namespace scope             | Copy NADs and the `rivermax-license` secret into the deployment namespace when they exist in another project (for example, `default`). | [Namespace Scope](#namespace-scope)                                                             |
| NGC account and API key                    | Required for CLI authentication, image and chart pulls, and creating image pull and model pull secrets.                                                                                         | [NGC Authentication](#ngc-authentication)                                                         |
| Rivermax license                           | Required for SMPTE ST 2110 streaming.                                                                                                                                                           | [Rivermax License](#rivermax-license)                                                             |
| High-speed network attachment              | A `NetworkAttachmentDefinition` for SMPTE ST 2110 provisioned by the cluster administrator.                                                                                                     | [High-Speed Network Configuration](#high-speed-network-configuration)                             |
| NMOS registry (optional)                   | Required only when using NMOS for dynamic stream connection management.                                                                                                                         | —                                                                                                 |
| Chrome Remote Desktop (when using NMOS)    | Required to reach the NMOS Connection Manager UI in Holoscan for Media setups.                                                                                                                  | [Chrome Remote Desktop](#chrome-remote-desktop)                                                   |
| Topology-aware scheduler (when applicable) | Required on some clusters with strict NUMA policies so sender, NIM, and receiver pods in the sample chart can schedule.                                                                         | [Scheduler Requirements for NUMA-aware Clusters](#scheduler-requirements-for-numa-aware-clusters) |


---

## OpenShift Setup

Complete the following steps before deployment.

### 1. Create Namespace

```bash
kubectl create namespace <namespace>
```

On OpenShift you can use `oc new-project <namespace>` instead; the command creates the namespace and can set additional project defaults (for example, display name). The remaining steps, including SCC binding, apply the same either way.

### 2. Grant SCC Permission

Grant the required OpenShift SCC permission to the service account that runs your pods. Many deployments use the namespace `default` account when `spec.serviceAccountName` is unset; if your Helm chart, operator custom resource, or pod template sets a different account, use that name with `-z`.

```bash
oc adm policy add-scc-to-user privileged -z <service-account-name> -n <namespace>
```

For example, when workloads run as `default`:

```bash
oc adm policy add-scc-to-user privileged -z default -n <namespace>
```

To discover the account name for an existing pod:

```bash
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.serviceAccountName}{"\n"}'
```

An empty result means that the namespace default service account is used. Grant SCC separately for each distinct service account that runs operator-managed media functions, LipSync NIM, or sample chart pods in this namespace.

Without this step, pods might fail with security context constraint errors.

---

## Namespace Scope

After the namespace exists and SCC permissions are in place, copy namespace-scoped resources into the deployment namespace when they already exist elsewhere on the cluster (commonly the `default` project).

The Multus network name you set in Helm (`network.name` or `global.network.name`) must match the `NetworkAttachmentDefinition` you deploy or copy into this namespace. For details on how to choose and configure that name, refer to [High-Speed Network Configuration](#high-speed-network-configuration).

### 1. Copy NetworkAttachmentDefinitions (NADs)

NADs are namespace-scoped resources.

Check available NADs:

```bash
kubectl get net-attach-def -A
```

If the required NADs exist in another namespace (commonly `default`), copy them into the deployment namespace:

```bash
NS_DST=<namespace>

for nad in $(kubectl get net-attach-def -n default -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}'); do
  kubectl get net-attach-def "$nad" -n default -o json | jq --arg ns "$NS_DST" '
    del(.metadata.uid,
        .metadata.resourceVersion,
        .metadata.creationTimestamp,
        .metadata.generation,
        .metadata.managedFields) |
    .metadata.namespace = $ns
  ' | kubectl apply -f -
done
```

Without this step, pods might fail with the following error:

```text
NetworkAttachmentDefinition "<name>" not found
```

### 2. Copy Rivermax License Secret

If the `rivermax-license` secret exists in another namespace (commonly `default`), copy it into the deployment namespace:

```bash
NS_DST=<namespace>

kubectl get secret rivermax-license -n default -o json | jq --arg ns "$NS_DST" '
  del(.metadata.uid,
      .metadata.resourceVersion,
      .metadata.creationTimestamp,
      .metadata.managedFields,
      .metadata.ownerReferences) |
  del(.metadata.annotations."kubectl.kubernetes.io/last-applied-configuration") |
  .metadata.namespace = $ns
' | kubectl apply -f -
```

On Red Hat OpenShift, you can use `oc` instead of `kubectl` in the commands above.

---

## Scheduler Requirements for NUMA-aware Clusters

The sender, LipSync NIM, and receiver workloads request dedicated CPU, GPU, memory, and hugepages resources. Resource requirements vary by component. The following example shows the LipSync NIM container configuration:

```yaml
resources:
  limits:
    cpu: 8
    hugepages-2Mi: 4Gi
    memory: 8Gi
    nvidia.com/gpu: 1
  requests:
    cpu: 8
    hugepages-2Mi: 4Gi
    memory: 8Gi
    nvidia.com/gpu: 1
```

On clusters configured with strict NUMA policies (for example, `topologyManagerPolicy=single-numa-node`), a topology-aware scheduler might be required to successfully place the sender, NIM, and receiver pods.

The Helm chart exposes `schedulerName` as a configurable parameter.

For NUMA-aware deployments, configure `schedulerName` as follows:

```yaml
schedulerName: topo-aware-scheduler
```

OpenShift users can install the NUMA Resources Operator (NRO), which provides `topo-aware-scheduler`.

On clusters without a topology-aware scheduler, you can configure `schedulerName` as follows:

```yaml
schedulerName: default-scheduler
```

This configuration assumes that the cluster topology can satisfy the workload resource requirements.

If pods remain in `Pending` state with `FailedScheduling` events mentioning NUMA alignment or topology constraints, verify the following:

- Topology Manager configuration
- Availability of hugepages
- Alignment of CPU and GPU resources
- Scheduler configuration

---

## Access NGC and Helm Charts

An [NGC](https://catalog.ngc.nvidia.com/) account and an [NGC API key](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys) are required to authenticate the CLI, pull container images and Helm charts from NVIDIA registries, and create cluster pull secrets as described in [License and Secrets Management](#license-and-secrets-management).

### NGC Authentication

#### Generate an API Key

An NGC API key is required to access NGC resources. You can generate a key at [https://org.ngc.nvidia.com/setup/api-keys](https://org.ngc.nvidia.com/setup/api-keys).

When creating an NGC API Personal key, ensure that at least **NGC Catalog** is selected from the **Services Included** dropdown. You can include more services if this key is to be reused for other purposes.

<Note>
Personal keys allow you to configure an expiration date, revoke or delete the key using an action button, and rotate the key as needed. For more information about key types, refer to [NGC API Keys](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys) in the NGC User Guide.
</Note>

#### Export the NGC API Key

To pull container images and model artifacts from NGC, use the `NGC_API_KEY` environment variable when authenticating with the Helm registry and creating cluster secrets as described in the following sections.

The simplest way to create the `NGC_API_KEY` environment variable is to export it in your terminal:

```bash
export NGC_API_KEY=<value>
```

Run one of the following commands to make the key available at startup:

```bash
# If using bash
echo "export NGC_API_KEY=<value>" >> ~/.bashrc

# If using zsh
echo "export NGC_API_KEY=<value>" >> ~/.zshrc
```

<Note>
Other, more secure options include saving the value in a file, so that you can retrieve with `cat $NGC_API_KEY_FILE`, or using a [password manager](https://www.passwordstore.org/).
</Note>

#### Log In to the NGC Registry

Log in to the NGC container and Helm registry before pulling charts or images:

```bash
helm registry login nvcr.io --username '$oauthtoken' --password $NGC_API_KEY
```

## License and Secrets Management

### Rivermax License

[Rivermax](https://docs.nvidia.com/holoscan-for-media/latest/user-guide/getting-help/rivermax-st-2110.html#rivermax-help) is an optimized networking SDK that uses ConnectX and BlueField DPU hardware-streaming acceleration and supports GPUDirect, in bare metal and virtualized environments. Rivermax is required by Holoscan for Media applications to comply with the timing and traffic flow requirements of SMPTE ST 2110.

Request a development license at [Rivermax Download](https://developer.nvidia.com/networking/rivermax-getting-started). When the license file is available, create a Kubernetes secret from it:

```bash
kubectl create secret generic rivermax-license \
  --from-file=rivermax.lic \
  -n <your-namespace>
```

The Helm chart mounts this secret into the container at `/opt/mellanox/rivermax`.

On Red Hat OpenShift, replace `kubectl` with `oc`.

### Image Pull Secret

Create a secret so the cluster can pull images from `nvcr.io`:

```bash
kubectl create secret docker-registry <secret-name> \
  --docker-server=nvcr.io \
  '--docker-username=$oauthtoken' \
  --docker-password=<NGC-API-KEY> \
  --docker-email=<your-email> \
  -n <your-namespace>
```

On Red Hat OpenShift, replace `kubectl` with `oc`.

Example:

```bash
oc create secret docker-registry ngc-secret-key \
  --docker-server=nvcr.io \
  '--docker-username=$oauthtoken' \
  --docker-password=MY-NGC-API-KEY \
  --docker-email=test@nvidia.com
```

- `<secret-name>`: Name for the image pull secret.
- `<NGC-API-KEY>`: The [NGC API key](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys) for the org that hosts the images.
- `<your-email>`: The email address associated with the NGC account.
- `<your-namespace>`: The Kubernetes namespace in which applications are deployed; often `default` when getting started.

### Model Pull Secret

Model artifacts are downloaded by the NIM at runtime using an API key carried in a generic secret, separate from the image pull secret discussed earlier:

```bash
kubectl create secret generic <secret-name> \
  --from-literal=NGC_API_KEY=<NGC-API-KEY> \
  -n <your-namespace>
```

Example:

```bash
kubectl create secret generic model-download-api-key \
  --from-literal=NGC_API_KEY=MY-NGC-API-KEY
```

On Red Hat OpenShift, replace `kubectl` with `oc`.

- `<secret-name>`: Name for the model pull secret.
- `<NGC-API-KEY>`: The [NGC API key](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys) for the org that hosts model artifacts.

---

## High-Speed Network Configuration

SMPTE ST 2110 media transport uses a dedicated high-speed network attachment provisioned on the cluster. The network attachment name must match the `NetworkAttachmentDefinition` configured by your cluster administrator.

Set the network attachment name in the Helm values for each component in the pipeline. A single attachment is configured as follows:

```yaml
highSpeedNetwork:
  name: "media-a-tx-net"
```

For multiple network attachments, use the list format:

```yaml
highSpeedNetwork:
  - name: "media-a-tx-net"
  - name: "media-b-tx-net-static"
    ip: "198.51.100.3/24"
```

For networks with static IP address management, the `ip` property is required in addition to the network name.

<Note>
To ensure correct media routing, the network attachment name must be the same across all components in the pipeline—sender, NIM service, and receiver.
</Note>

---

## Chrome Remote Desktop

When LipSync is deployed with NMOS enabled, streams are connected and managed through the NMOS Connection Manager (a web UI). On Holoscan for Media clusters, access to that UI typically requires a browser that can reach the cluster network. Chrome Remote Desktop provides a remote graphical session for accessing that UI.

For information about installation and setup, refer to the [Chrome Remote Desktop](https://docs.nvidia.com/holoscan-for-media/latest/user-guide/app-deployment/manual/manual-deployment.html#chrome-remote-desktop) section of [Manual Deployment](https://docs.nvidia.com/holoscan-for-media/latest/user-guide/app-deployment/manual/manual-deployment.html) in the Holoscan for Media user guide.

---

## Security Context

The NIM container requires the following Linux capabilities to operate correctly:


| Capability        | Purpose                                                          |
| ----------------- | ---------------------------------------------------------------- |
| `IPC_LOCK`        | Lock memory pages; required for hugepage allocation by Rivermax. |
| `NET_RAW`         | Use raw sockets; required by Rivermax for SMPTE ST 2110.         |
| `SYS_NICE`        | Set process and thread CPU affinity; required by Rivermax.       |
| `DAC_READ_SEARCH` | Read files across permission boundaries during startup.          |


These capabilities are set in the Helm values under `containerSecurityContext` or in the NIM operator custom resource under `spec.parameters.securityContext`. For details, refer to [Configuration Reference](/nim/maxine/lipsync-h4m/configuration).

---

## See Also

- [Installation](/nim/maxine/lipsync-h4m/installation/index): Instructions for demo, service, and operator Helm install instructions.
- [Configuration Reference](/nim/maxine/lipsync-h4m/configuration): Helm, operator, and environment variable tables with defaults and allowed values.