> This page is for NVIDIA Studio Voice NIM, version 1.1.0.
> For other versions, use one of these documentation indexes:
> - 1.2.1 (Latest) (default): https://docs.nvidia.com/nim/maxine/studio-voice/1.2.1/llms.txt
> - 1.2.0: https://docs.nvidia.com/nim/maxine/studio-voice/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/maxine/studio-voice/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/maxine/studio-voice/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

## Prerequisites

Check the [Support Matrix](/nim/maxine/studio-voice/1.1.0/support-matrix) to make sure that you have the supported hardware and software stack.

NVIDIA NIM for Studio Voice can run on Linux or on Windows (under WSL2).

### Running on Windows

You can run NVIDIA NIM for Studio Voice on RTX in a Windows-based system with Windows Subsystem for Linux (WSL) after taking the following additional steps.

<Note>
Support for NIMs on WSL is in Public Beta.
</Note>

1. Refer to the [NVIDIA NIM on WSL](https://docs.nvidia.com/nim/wsl2/latest/) documentation for setup instructions.

2. Refer to the [NIM Model Profile Table](/nim/maxine/studio-voice/1.1.0/model-profile-table) to ensure that hardware and software requirements are met.

    By default, WSL has access to half of system RAM. To change the memory available for WSL, create `.wslconfig` in the home directory `C:\Users\<UserName>` with the following content:

    ```text
    # Settings apply across all Linux distros running on WSL
    [wsl2]

    # Limits RAM memory to use no more than 38 GB. Can be set as whole numbers using GB or MB.
    memory=38GB

    ```

    Restart WSL instances to apply the configuration:

    ```bash
    wsl --shutdown
    ```

    For any issues related to WSL setup, refer to [Troubleshooting](https://docs.nvidia.com/nim/wsl2/latest/troubleshooting.html) in the NVIDIA NIM on WSL2 documentation.

    For any issues related to port forwarding, refer to [Setting Up Port Forwarding](https://docs.nvidia.com/nim/wsl2/latest/running-client-port-forwarding.html).

3. Use the `podman` command examples in the following sections.

### NGC Authentication

#### Generate an API Key

An NGC API key is required to access NGC resources. You can generate a key at [NGC 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. More Services can be included 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, please refer the [NGC User Guide](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys).
</Note>

#### Export the API Key

Pass the value of the API key to the `docker run` command in the next section as the `NGC_API_KEY` environment variable to download the appropriate models and resources when starting the NIM.

If you are not familiar with how to create the `NGC_API_KEY` environment variable, the simplest way 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>

#### Docker Login to NGC

To pull the NIM container image from NGC, first authenticate with the NVIDIA Container Registry with the following command:

<Tabs>
<Tab title="docker" language="docker">

```bash
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
```

</Tab>
<Tab title="podman" language="podman">

```bash
echo "$NGC_API_KEY" | podman login nvcr.io --username '$oauthtoken' --password-stdin
```

</Tab>
</Tabs>

Use `$oauthtoken` as the username and `NGC_API_KEY` as the password. The `$oauthtoken` username is a special name that indicates that you will authenticate with an API key and not a user name and password.

## Starting the NIM Container

The following command launches the Studio Voice NIM container with the gRPC service. Find reference to runtime parameters for the container [here](#runtime-parameters-for-the-container).

Transactional NIM:

<Tabs>
<Tab title="docker" language="docker">

```bash
docker run -it --rm --name=studio-voice \
    --runtime=nvidia \
    --gpus all \
    --shm-size=8GB \
    -e NGC_API_KEY=$NGC_API_KEY \
    -e NIM_MODEL_PROFILE=<nim_model_profile> \
    -e FILE_SIZE_LIMIT=36700160 \
    -e STREAMING=false \
    -p 8000:8000 \
    -p 8001:8001 \
    nvcr.io/nim/nvidia/maxine-studio-voice:latest
```

</Tab>
<Tab title="podman" language="podman">

```bash
podman run -it --rm --name=studio-voice \
    --device nvidia.com/gpu=all \
    --shm-size=8GB \
    -e NGC_API_KEY=$NGC_API_KEY \
    -e FILE_SIZE_LIMIT=36700160 \
    -e STREAMING=false \
    -p 8000:8000 \
    -p 8001:8001 \
    nvcr.io/nim/nvidia/maxine-studio-voice:latest
```

</Tab>
</Tabs>

Streaming NIM:

<Tabs>
<Tab title="docker" language="docker">

```bash
docker run -it --rm --name=studio-voice \
    --runtime=nvidia \
    --gpus all \
    --shm-size=8GB \
    -e NGC_API_KEY=$NGC_API_KEY \
    -e NIM_MODEL_PROFILE=<nim_model_profile> \
    -e FILE_SIZE_LIMIT=36700160 \
    -e STREAMING=false \
    -p 8000:8000 \
    -p 8001:8001 \
    nvcr.io/nim/nvidia/maxine-studio-voice:latest
```

</Tab>
<Tab title="podman" language="podman">

```bash
podman run -it --rm --name=studio-voice \
    --device nvidia.com/gpu=all \
    --shm-size=8GB \
    -e NGC_API_KEY=$NGC_API_KEY \
    -e FILE_SIZE_LIMIT=36700160 \
    -e STREAMING=true \
    -p 8000:8000 \
    -p 8001:8001 \
    nvcr.io/nim/nvidia/maxine-studio-voice:latest
```

</Tab>
</Tabs>

<Note>
The flag `--gpus all` is used to assign all available GPUs to the docker container. This fails on multiple GPU unless all GPUs are same. To assign specific GPU to the docker container (in case of different multiple GPUs available in your machine) use `--gpus '"device=0,1,2..."'`
</Note>

<Note>
Please note, required VRAM resource for running the NIM, varies between 2.3 and 3.7 GB VRAM depending on the model profile.
</Note>

If the command runs successfully, you will get an output ending similar to the following:

```bash
I1126 09:22:21.048202 31 grpc_server.cc:2558] "Started GRPCInferenceService at 127.0.0.1:9001"
I1126 09:22:21.048377 31 http_server.cc:4704] "Started HTTPService at 127.0.0.1:9000"
I1126 09:22:21.089295 31 http_server.cc:362] "Started Metrics Service at 127.0.0.1:9002"
Maxine GRPC Service: Listening to 0.0.0.0:8001
```

<Note>
By default, the Studio Voice gRPC service is hosted on port `8001`. You must use this port for inferencing requests.
</Note>

### Selecting a Model Profile

Note that `NIM_MODEL_PROFILE` is an optional parameter. If `NIM_MODEL_PROFILE` is not provided, the NIM automatically selects a matching `NIM_MODEL_PROFILE` based on the target hardware architecture.

If `STREAMING` is set to `true`, the NIM automatically selects a profile that is compatible with your GPU of [Model Type](/nim/maxine/studio-voice/1.1.0/model-profile-table#model-type) `48k-LL`.

If `STREAMING` is set to `false`, the NIM automatically selects a profile that is compatible with your GPU of [Model Type](/nim/maxine/studio-voice/1.1.0/model-profile-table#model-type) `48k-HQ`.

However, if `NIM_MODEL_PROFILE` is used, ensure that the associated GPU architecture is compatible with the target hardware. If an incorrect `NIM_MODEL_PROFILE` is used, a deserialization error will occur on inference.

If a non-supported GPU is used for launching the NIM, you get an error:
`nimlib.exceptions.NIMProfileIDNotFound: Could not match a profile in manifest at /opt/nim/etc/default/model_manifest.yaml`.

For more information about `NIM_MODEL_PROFILE`, refer to the [NIM Model Profile Table](https://docs.nvidia.com/nim/maxine/studio-voice/latest/model-profile-table.html).

## Environment Variables

The following table describes the environment variables that can be passed into a NIM as a `-e` argument added to a `docker run` command:

| ENV                 | Required? | Default | Notes |
| ------------------- | --------- | ------- | ----- |
| `NGC_API_KEY`       | Yes | None | You must set this variable to the value of your personal NGC API key. |
| `NIM_CACHE_PATH`    | No  | `/opt/nim/.cache` | Location (in container) where the container caches model artifacts. |
| `NIM_MODEL_PROFILE` | Optional | None | You must set this model profile to be able to download the specific model type supported on your GPU. To know more about `NIM_MODEL_PROFILE`, refer to the [NIM Model Profile Table](/nim/maxine/studio-voice/1.1.0/model-profile-table). |
| `FILE_SIZE_LIMIT`   | No  | 36700160 | Maximum size limit of the input audio file in bytes. This is applicable only for the transactional mode. Defaults to 35 MB. |
| `STREAMING`         | No  | false | Enable audio streaming mode on gRPC endpoint if set to `true`. |
| `NIM_SSL_MODE`      | No  | disabled | Set SSL security on the endpoints to `tls` or `mtls`. Defaults to unsecured endpoint. |
| `NIM_SSL_CA_PATH`   | No  | None | Set the path to CA root certificate inside the NIM. This is required only when `NIM_SSL_MODE` is `mtls`. For example, if the SSL certificates are mounted at `/opt/nim/crt` in the NIM, `NIM_SSL_CA_PATH` can be set to `/opt/nim/crt/ssl_ca_cert.pem`. |
| `NIM_SSL_CERT_PATH` | No  | None | Set the path to the server's public SSL certificate inside the NIM. This is required only when an SSL mode is enabled. For example, if the SSL certificates are mounted at `/opt/nim/crt` in the NIM, `NIM_SSL_CERT_PATH` can be set to `/opt/nim/crt/ssl_cert_server.pem`. |
| `NIM_SSL_KEY_PATH`  | No  | None | Set the path to the server's private key inside the NIM. This is required only when an SSL mode is enabled. For example, if the SSL certificates are mounted at `/opt/nim/crt` in the NIM,`NIM_SSL_KEY_PATH` can be set to `/opt/nim/crt/ssl_key_server.pem`. |

## Runtime Parameters for the Container

| Flags  | Description |
|--------|-------------|
| `-it`  | `--interactive` + `--tty` (see [Docker docs](https://docs.docker.com/reference/cli/docker/container/run/)) |
| `--rm` | Delete the container after it stops (see [Docker docs](https://docs.docker.com/reference/cli/docker/container/run/)) |
| `--name=<container_name>` | Give a name to the NIM container. Use any preferred value. |
| `--runtime=nvidia`        | Ensure NVIDIA drivers are accessible in the container. |
| `--gpus all` | Expose NVIDIA GPUs inside the container. If you are running on a host with multiple GPUs, you need to specify which GPU to use, you can also specify multiple GPUs. See [GPU Enumeration](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html) for further information on for mounting specific GPUs. |
| `--shm-size=8GB`              | Allocate host memory for multi-process communication. |
| `-e NGC_API_KEY=$NGC_API_KEY` | Provide the container with the token necessary to download adequate models and resources from NGC. See [above](#ngc-authentication). |
| `-p <host_port>:<container_port>` | Ports published by the container are directly accessible on the host port. |

## Stopping the Container

The following commands can be used to stop the container.

<Tabs>
<Tab title="docker" language="docker">

```bash
docker stop $CONTAINER_NAME
docker rm $CONTAINER_NAME
```

</Tab>
<Tab title="podman" language="podman">

```bash
podman stop $CONTAINER_NAME
podman rm $CONTAINER_NAME
```

</Tab>
</Tabs>