> This page is for NVIDIA Active Speaker Detection 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/active-speaker-detection-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

Check the [Support Matrix](/nim/maxine/active-speaker-detection-h4m/support-matrix) to verify that the required hardware and software are available before proceeding.


| Requirement                                | Details                                                                                                                                                                                    | Reference                                                                                         |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| Kubernetes cluster                         | Kubernetes or Red Hat OpenShift.                                                                                                                                                           | [Support Matrix](/nim/maxine/active-speaker-detection-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 namespace (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) |


## 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 both 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`.

- `<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 ngc-model-pull-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>

---

(openshift-setup)=
## 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, NIM, or sample chart pods in this namespace.

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

---

(namespace-scope)=
## 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).

### 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)=
## Scheduler Requirements for NUMA-Aware Clusters

Some clusters enforce NUMA-aware scheduling policies that prevent pods from being scheduled by the default Kubernetes scheduler when they request resources such as hugepages, GPUs, or CPU sets. In these environments, the `topo-aware-scheduler` is required for the sender, NIM service, and receiver pods to schedule correctly.

Confirm whether your cluster uses a topology-aware scheduler:

```bash
kubectl get pods -n <scheduler-namespace> | grep topo
```

If the scheduler is present, set `schedulerName: topo-aware-scheduler` in your Helm values or pass it as an override:

```bash
--set schedulerName=topo-aware-scheduler
```

For the end-to-end sample chart, use the `global` override to apply it to all components at once:

```bash
--set global.schedulerName=topo-aware-scheduler
```

If the scheduler is not present or not required on your cluster, the default Kubernetes scheduler is used and no action is needed.

---

(chrome-remote-desktop)=
## Chrome Remote Desktop

When Active Speaker Detection 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/active-speaker-detection-h4m/configuration).

---

## See Also

- [Installation](/nim/maxine/active-speaker-detection-h4m/installation/index) — Instructions for demo, service, and operator Helm installation.
- [Configuration Reference](/nim/maxine/active-speaker-detection-h4m/configuration) — Helm, operator, and environment variable tables with defaults and allowed values.