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

# Kubernetes Operator Chart

## Overview

The `nvidia-studio-voice-h4m-operator` Helm chart installs the Studio Voice Kubernetes operator. The controller watches `NvidiaStudioVoiceMediaFunction` custom resources and reconciles a deployment for the Studio Voice NIM, SDP ConfigMaps (`/sdps`), and status.

- **Operator chart:** Deploys only the controller and CRDs. It does not install an `NvidiaStudioVoiceMediaFunction` custom resource or the NIM workload—apply a custom resource after installation to provision the NIM.
- **Operand:** Each custom resource instance drives one Studio Voice NIM workload (audio in and enhanced audio out) according to the inputs, outputs, and parameters declared in that resource.

---

## Installation

### Prerequisites

Before running `helm install`, complete all prerequisite steps (Rivermax license, image pull and model pull secrets, GPU node, Multus attachment for SMPTE ST 2110). For more information, refer to [Getting Started](/nim/maxine/studio-voice-h4m/getting-started).

### Pull the Chart

If not already done, add the Helm repository and pull the chart:

```bash
helm pull nim-repo/nvidia-studio-voice-h4m-operator --version 1.2.0
```


For the full repository setup, refer to [Pull Helm Charts](/nim/maxine/studio-voice-h4m/installation/index#pull-helm-charts).

### Helm Installation

The chart installs the operator deployment and registers the `NvidiaStudioVoiceMediaFunction` CRD. For all available Helm values and `--set` keys, refer to [Operator Configuration](/nim/maxine/studio-voice-h4m/configuration/operator).

The chart expects a pre-created image pull secret for `nvcr.io` (default name `ngc-api-key`). If your secret names differ, override as follows:

```bash
helm install studio-voice-operator \
  nvidia-studio-voice-h4m-operator-1.2.0.tgz \
  --set imagePullSecrets[0].name=<operator-pull-secret> \
  --set mediaFunction.imagePullSecrets[0].name=<nim-pull-secret>
```


When the defaults match your cluster, you can use the following command:

```bash
helm install studio-voice-operator \
  nvidia-studio-voice-h4m-operator-1.2.0.tgz
```


| `--set` Flag | Purpose | Default |
|---|---|---|
| `imagePullSecrets[0].name` | Image pull secret for the operator pod. | `ngc-api-key` |
| `mediaFunction.imagePullSecrets[0].name` | Image pull secret for NIM pods that the operator creates. | `ngc-api-key` |
| `imageCredentials.password` | Inline registry password for the operator (alternative to a pre-created secret). | `""` |
| `mediaFunction.imageCredentials.password` | Inline registry password for NIM pods. | `""` |

<Note>
The model pull secret and node hostname are set on the custom resource, not Helm values (`spec.parameters.ngcSecret`, `spec.nodeSelector`). Refer to [Create the Custom Resource](#create-the-custom-resource).
</Note>

<Note>
If `helm install` fails with an `Apply failed with 1 conflict` error citing the `NvidiaStudioVoiceMediaFunction` CRD, the CRD was previously applied with `kubectl apply` (field manager `kubectl-client-side-apply`) and Helm cannot take ownership of its fields. Take over the field manager once with `kubectl replace`, and then re-run `helm install`:

```bash
tar xf nvidia-studio-voice-h4m-operator-1.2.0.tgz
kubectl replace -f nvidia-studio-voice-h4m-operator/crds/nvidiastudiovoicemediafunction-crd.yaml
helm install studio-voice-operator nvidia-studio-voice-h4m-operator-1.2.0.tgz
```


On Red Hat OpenShift, replace `kubectl` with `oc`.
</Note>

Wait for the controller to be ready:

```bash
kubectl rollout status deployment/studio-voice-operator-controller-manager --timeout=180s
```

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

---

## Create the Custom Resource

After the operator controller is ready, save a manifest (for example, `studio-voice-media-function.yaml`) and configure the following areas:

| Area | Field | Notes |
|------|-------|-------|
| GPU node | `spec.nodeSelector` | Labels for the node that runs the NIM pod (for example, `kubernetes.io/hostname`). |
| Model pull secret | `spec.parameters.ngcSecret.secretName` | Must match the model pull secret created in [Getting Started](/nim/maxine/studio-voice-h4m/getting-started#model-pull-secret). |
| Pipeline I/O | `spec.inputs` / `spec.outputs` | SMPTE ST 2110 *static* (fixed sessions and addresses) or NMOS-managed connections. |
| Pipeline tuning | `spec.parameters` | Refer to [Operator Configuration](/nim/maxine/studio-voice-h4m/configuration/operator). |

Apply the manifest:

```bash
kubectl apply -f studio-voice-media-function.yaml
```

Applying the CR reconciles and starts the Studio Voice NIM in NMOS mode; refer to [Chrome Remote Desktop](/nim/maxine/studio-voice-h4m/getting-started#chrome-remote-desktop) for NMOS Connection Manager UI access and setup steps.

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

### Example Manifest

Reference a custom resource with a placeholder node name, `ngc-api-key` for model download, and audio format defaults.

```yaml
apiVersion: nvidia.com/v1alpha1
kind: NvidiaStudioVoiceMediaFunction
metadata:
  labels:
    app.kubernetes.io/name: studio-voice-operator
    app.kubernetes.io/managed-by: helm
  name: nvidia-studio-voice-nim-media-function
spec:
  schedulerName: topo-aware-scheduler
  nodeSelector:
    kubernetes.io/hostname: <gpu-node-name>

  parameters:
    highSpeedNetwork:
      - name: media-a-tx-net
    resources:
      requests:
        cpu: "4"
        memory: "8Gi"
        hugepages-2Mi: "2Gi"
        nvidia.com/gpu: "1"
      limits:
        cpu: "4"
        memory: "8Gi"
        hugepages-2Mi: "2Gi"
        nvidia.com/gpu: "1"
    ngcSecret:
      secretName: ngc-api-key
      secretKey: NGC_API_KEY
    nimModelCache:
      path: /opt/nim/.cache
      pvc:
        enabled: false
        # claimName: <CR.name>-model-cache       # default
        size: 10Gi
        # storageClassName: ""                    # empty -> cluster default
    nimLogs:
      path: /workspace/nim-logs
      pvc:
        enabled: false
        # claimName: <CR.name>-nim-logs          # default
        size: 5Gi
        # storageClassName: ""                    # empty -> cluster default
    securityContext:
      runAsUser: 1000
      runAsGroup: 1000
      runAsNonRoot: true
      allowPrivilegeEscalation: true
      capabilities:
        add:
          - IPC_LOCK
          - NET_RAW
          - SYS_NICE
          - DAC_READ_SEARCH
        drop:
          - ALL
    podSecurityContext:
      fsGroup: 1000
      seccompProfileType: RuntimeDefault
    label: "Studio-Voice-NIM"
    description: "Studio Voice NIM - audio enhancement, ST2110"
    nmosEnabled: true
    nimEnabled: true
    loggingLevel: 3

  inputs:
    audio_input:
      control:
        nmos: {}
      transport:
        rtp:
          packet_time: 1
      format:
        audio:
          sample_rate: 48000
          channel_count: 1
          sample_depth: 24
          media_type: "audio/L24"
      sessionName: audio_in
      localInterfaceName: net1
      hostIP: "234.5.8.9"
      hostPort: "5003"
      hostNumSubnetBits: 24

  outputs:
    audio_output:
      control:
        nmos: {}
      transport:
        rtp:
          packet_time: 1
      format:
        audio:
          sample_rate: 48000
          channel_count: 1
          sample_depth: 24
          media_type: "audio/L24"
      sessionName: audio_out
      localInterfaceName: net1
      hostIP: "234.5.8.9"
      hostPort: "5004"
      hostNumSubnetBits: 24
```

### Extended Parameters (Optional)

As needed, you can add optional `spec.parameters` fields, including `resources` (CPU, memory, GPU, hugepages) and `nimLogs` / `nimModelCache` PVC settings (`path`, `pvc.enabled`, `pvc.size`, `pvc.storageClassName`, `pvc.claimName`). For field-by-field details, refer to [Operator Configuration](/nim/maxine/studio-voice-h4m/configuration/operator) in the configuration reference. For PVC configuration, refer to [Advanced Usage](/nim/maxine/studio-voice-h4m/advanced-usage#persistent-storage). CPU affinity is set on the NIM service Helm chart (`env.CPU_AFFINITY`) and is not exposed on the custom resource.

---

## Verify

After applying the custom resource:

```bash
kubectl get nvidiastudiovoicemediafunctions
kubectl get pods -l app.kubernetes.io/managed-by=studio-voice-operator
```

Inspect custom resource status conditions:

```bash
kubectl get nvidiastudiovoicemediafunction <cr-name> \
  -o json | jq '.status.conditions'
```

Confirm the CRD is installed:

```bash
kubectl get crd nvidiastudiovoicemediafunctions.nvidia.com
```

On Red Hat OpenShift, replace `kubectl` with `oc`. For log access, refer to [Observability](/nim/maxine/studio-voice-h4m/observability#logs).

---

## Uninstall

First, delete all custom resource instances so the operator can remove the managed deployments and ConfigMaps; then remove the Helm release. Delete the CRD cluster-wide only if coordinated with cluster administrators; it affects all namespaces.

```bash
kubectl delete nvidiastudiovoicemediafunctions.nvidia.com --all
helm uninstall studio-voice-operator
# Optional — removes the custom resource definition cluster-wide:
kubectl delete crd nvidiastudiovoicemediafunctions.nvidia.com
```

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

<Note>
The `*-model-cache` and `*-nim-logs` PVCs carry `helm.sh/resource-policy: keep` and are *not* removed by `helm uninstall`. This preserves the cached model across reinstalls; clean them up manually when no longer needed:

```bash
kubectl delete pvc -l app.kubernetes.io/instance=studio-voice-operator -n <your-namespace>
```
</Note>

For troubleshooting and known limitations, refer to [Advanced Usage](/nim/maxine/studio-voice-h4m/advanced-usage).

---

## See Also

- [Getting Started](/nim/maxine/studio-voice-h4m/getting-started) — NGC authentication, secrets, and prerequisites.
- [Installation](/nim/maxine/studio-voice-h4m/installation/index) — Service, operator, and demo chart installation patterns.
- [Configuration Reference](/nim/maxine/studio-voice-h4m/configuration) — Helm values and operator custom resource field reference.