voice-live-avatar

Instructions to run Microsoft Azure Voice Live with Avatar sample code

This sample demonstrates the usage of Azure Voice Live API with avatar.

Prerequisites

• Docker installed on your machine. You can download and install Docker from here.
• An active Azure account. If you don't have an Azure account, you can create a account here.
• A Microsoft Foundry resource created in one of the supported regions. For more information about region availability, see the voice live overview documentation.

Avatar available locations

The avatar feature is currently available in the following service regions: Southeast Asia, North Europe, West Europe, Sweden Central, South Central US, East US 2, and West US 2.

Build the sample

To run the sample, you need to build it into a Docker image. Navigate to the folder containing this README.md document (make sure you are inside the right directory):

# Windows (PowerShell/Command Prompt)
cd .\javascript\voice-live-avatar\

# macOS/Linux (Terminal)
cd ./javascript/voice-live-avatar/

Run below command to build the Docker image:

docker build -t voice-live-avatar .

This command will create a Docker image named voice-live-avatar.

Start the sample

To start the sample, use the following command:

docker run --rm -p 3000:3000 voice-live-avatar

Then open your web browser and navigate to http://localhost:3000 to access the sample.

Configure and play the sample

• Step 1: Under the Connection Settings section, fill Azure AI Services Endpoint and Subscription Key, which can be obtained from the Keys and Endpoint tab in your Azure AI Services resource. The endpoint can be the regional endpoint (e.g., https://<region>.api.cognitive.microsoft.com/) or a custom domain endpoint (e.g., https://<custom-domain>.cognitiveservices.azure.com/).

• Step 2: Under Conversation Settings section, configure the avatar:

  • Enable Avatar: Toggle the Avatar switch to enable the avatar feature.
  • Avatar Type: By default, a prebuilt avatar is used. Select a character from the Avatar dropdown list.
    • To use a photo avatar, toggle the Use Photo Avatar switch and select a prebuilt photo avatar character from the dropdown list.
    • To use a custom avatar, toggle the Use Custom Avatar switch and enter the character name in the Character field.
  • Avatar Output Mode: Choose between WebRTC (default, real-time streaming) and WebSocket (streams video data over the WebSocket connection).
  • Avatar Background Image URL (optional): Enter a URL to set a custom background image for the avatar.
  • Scene Settings (photo avatar only): When using a photo avatar, adjust scene parameters such as Zoom, Position X/Y, Rotation X/Y/Z, and Amplitude. These settings can also be adjusted live after connecting.

• Step 3: Click Connect button to start the conversation. Once connected, you should see the avatar appearing on the page, and you can click Turn on microphone and start talking with the avatar with speech.

• Step 4: On top of the page, you can toggle the Developer mode switch to enable developer mode, which will show chat history in text and additional logs useful for debugging.

Deployment

This sample can be deployed to cloud for global access. The recommended hosting platform is Azure Container Apps. Here are the steps to deploy this sample to Azure Container Apps:

• Step 1: Push the Docker image to a container registry, such as Azure Container Registry. You can use the following command to push the image to Azure Container Registry:

  docker tag voice-live-avatar <your-registry-name>.azurecr.io/voice-live-avatar:latest
  docker push <your-registry-name>.azurecr.io/voice-live-avatar:latest

• Step 2: Create an Azure Container App and deploy the Docker image built from above steps, following Deploy from an existing container image. Make sure to set the environment variables as described in the previous sections, such as SPEECH_REGION, SPEECH_KEY, etc.

• Step 3: Once the Azure Container App is created, you can access the sample by navigating to the URL of the Azure Container App in your browser.