How to Build from Source#

Build the Audio Analyzer microservice from source to customize, debug, or extend its functionality. In this guide, you will:

Set up your development environment.
Compile the source code and resolve dependencies.
Generate a runnable build for local testing or deployment.

This guide is ideal for developers who want to work directly with the source code.

Prerequisites#

Before you begin, ensure the following:

System Requirements: Verify your system meets the minimum requirements.
This guide assumes basic familiarity with Git commands, Python virtual environments, and terminal usage. If you are new to these concepts, see:
- Git Documentation
- Python Virtual Environments
Follow all the steps provided in get started documentation with respect to environment variables configuration, setting up of storage backends and model selection.

Options to Build From Source#

The following options are provided to build the microservice:

Build and run application using Docker script.
Build and run on host using Setup script.
Build and run on host manually

Build and run in container using Docker script#

Clone the repository:

# Clone the latest on mainline
git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries
# Alternatively, Clone a specific release branch
git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries -b <release-tag>

Storage backend used in this setup is minio. We need to set following required environment variables for Minio on current shell:
```
# MinIO credentials (required)
export MINIO_ACCESS_KEY=<your-minio-username>
export MINIO_SECRET_KEY=<your-minio-password>
```
NOTE : If minio storage backend is not required, see Overriding Storage Backend.
The Docker setup will build the image if not already present on the machine. We can optionally set a registry URL and tag, if we wish to push this image to any repository. If not set, default image will be built as audio-analyzer:latest.
```
# Optional: Set registry URL and project name for docker image naming
export REGISTRY_URL=<your-registry-url>
export PROJECT_NAME=<your-project-name>
export TAG=<your-tag>
```
If REGISTRY_URL is provided, the final image name will be: ${REGISTRY_URL}${PROJECT_NAME}/audio-analyzer:${TAG} If REGISTRY_URL is not provided, the image name will be: ${PROJECT_NAME}/audio-analyzer:${TAG}

Set the required environment variables:

# (Required) Comma-separated list of models to download
export ENABLED_WHISPER_MODELS=small.en,tiny.en,medium.en

(OPTIONAL) You can customize the setup with these additional environment variables:

# Set a default model to use, if one is not provided explicitly. Should be one of the ENABLED_WHISPER_MODELS
export DEFAULT_WHISPER_MODEL=tiny.en
export MAX_FILE_SIZE=314572800

Run the setup script to build and bring up production version of application. This also brings up Minio Server container, if minio storage backend is used:
```
cd edge-ai-libraries/microservices/audio-analyzer
chmod +x ./setup_docker.sh
./setup_docker.sh
```
If above step is successful, it will print the complete URL of API endpoint along with URL of Swagger API docs. Please refer the API docs to learn how to send request to Audio-Analyzer when running with Minio.

Docker Setup Options#

The setup_docker.sh script when run without any parameters builds and runs the production docker images. It additionally supports the following options:

Options:
  --dev                 Build and run development environment
  --build               Only build production Docker image
  --build-dev           Only build development Docker image
  --down                Stop and remove all containers, networks,
                        and volumes
  -h, --help            Show this help message

Examples:

Production setup: ./setup_docker.sh
Development setup: ./setup_docker.sh --dev
Build production image only: ./setup_docker.sh --build
Build development image only: ./setup_docker.sh --build-dev
Stop and remove all containers: ./setup_docker.sh --down

The development environment provides:

Hot-reloading of code changes
Mounting of local code directory into container
Debug logging enabled

The production environment uses:

Gunicorn with multiple worker processes
Optimized container without development dependencies
No source code mounting (code is copied at build time)

Build and run on host using Setup Script#

Clone the repository:

# Clone the latest on mainline
git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries
# Alternatively, Clone a specific release branch
git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries -b <release-tag>

Run the setup script with desired options:

cd edge-ai-libraries/microservices/audio-analyzer
chmod +x ./setup_host.sh
./setup_host.sh

Available options:

--debug, -d: Enable debug mode
--reload, -r: Enable auto-reload on code changes

The setup script will:

Install all required system dependencies
Create directories for model storage. For host setup using script, only storage backend available is local filesystem.
Install Poetry and project dependencies
Start the Audio Analyzer service

Build and run on host manually#

NOTE : As an alternative easier method to setup on host, please see : setting up on host using setup script. When setting up on host manually, the storage backend used is local filesystem which can be overridden to minio. Please make sure the value of STORAGE_BACKEND environment variable is minio, unless you want to explicitly use the Minio storage backend.

Clone the repository and change directory to the audio-analyzer microservice:

# Clone the latest on mainline
git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries
# Alternatively, Clone a specific release branch
git clone https://github.com/open-edge-platform/edge-ai-libraries.git edge-ai-libraries -b <release-tag>
# Access the code
cd edge-ai-libraries/microservices/audio-analyzer

Install Poetry if not already installed.
```
pip install poetry==1.8.3
```

Configure poetry to create a local virtual environment.

poetry config virtualenvs.create true
poetry config virtualenvs.in-project true

Install dependencies:
```
poetry lock --no-update
poetry install
```
Set comma-separated list of whisper models that need to be enabled:
```
export ENABLED_WHISPER_MODELS=small.en,tiny.en,medium.en
```

Set directories on host where models will be downloaded:

export GGML_MODEL_DIR=/tmp/audio_analyzer_model/ggml
export OPENVINO_MODEL_DIR=/tmp/audio_analyzer_model/openvino

Run the service:

DEBUG=True poetry run uvicorn audio_analyzer.main:app --host 0.0.0.0 --port 8000 --reload

(Optional): To run the service with Minio storage backend, make sure Minio Server is running. Please see Running a Local Minio Server. User might need to update the MINIO_ENDPOINT environment variable depending on where the Minio Server is running (if not set, default value considered is localhost:9000).
```
export MINIO_ENDPOINT="<minio_host>:<minio_port>"
```
Run the Audio Analyzer application on host:
```
STORAGE_BACKEND=minio DEBUG=True poetry run uvicorn audio_analyzer.main:app --host 0.0.0.0 --port 8000 --reload
```

Running tests for host setup#

We can run unit tests and generate coverage by running following command in the application’s directory (microservices/audio-analyzer) in the cloned repo:

poetry lock --no-update
poetry install --with dev
# set a required env var to set model name : required due to compliance issue
export ENABLED_WHISPER_MODELS=tiny.en

# Run tests
poetry run coverage run -m pytest ./tests

# Generate Coverage report
poetry run coverage report -m

API Documentation#

When running the service, you can access the Swagger UI documentation at:

http://localhost:8000/docs

Validation#

Verify Build Success:
- Check the logs. Look for confirmation messages indicating the microservice started successfully.