CMVR-AI-ANALYSIS/README.md

CMVR Media Analysis Service

This service provides a project-neutral API for multi-label audio event classification and video analysis. Audio labels are discovered from reference subdirectories, so adding categories does not require code changes.

Runtime layout

The production deployment lives under /data/apps/cmvr-ai-analysis on the model server. Reference media belongs in data/profiles; generated features belong in data/artifacts.

Build an audio profile

Place at least three reference files in each label directory, then run:

docker compose run --rm analysis-service python -m tools.build_audio_profile \
  --profile-code aima.power_state.v1

On the model server the reference directories are:

/data/apps/cmvr-ai-analysis/data/profiles/aima/power-state/v1/references/POWER_ON
/data/apps/cmvr-ai-analysis/data/profiles/aima/power-state/v1/references/POWER_OFF
/data/apps/cmvr-ai-analysis/data/profiles/aima/power-state/v1/references/ARMED
/data/apps/cmvr-ai-analysis/data/profiles/aima/power-state/v1/references/DISARMED

After adding or replacing reference files, rebuild the feature library and restart the service profile state:

cd /data/apps/cmvr-ai-analysis
sh scripts/build-audio-profile.sh aima.power_state.v1
docker compose -f deploy/compose.yaml restart analysis-service

Run leave-one-out validation after rebuilding. Each sample is compared only with the other references, so a file cannot obtain a perfect score by matching itself:

sh scripts/validate-audio-profile.sh aima.power_state.v1

To add another sound category later, create a new stable uppercase label directory under references, add its display name to labelNames, upload the reference audio, and rebuild the profile. The classifier and platform workflow component do not need another code change.

API

POST /api/v1/analysis/run accepts requestId, analysisType, profileCode, mediaUrl, options, and context.

The deployed endpoint is http://192.168.28.10:14080. It is called by the platform backend and requires a bearer token.

The platform backend deployment must provide the same token through MEDIA_ANALYSIS_API_KEY. The service token is stored only in /data/apps/cmvr-ai-analysis/deploy/.env; it is not exposed to the browser or workflow JSON.

Video requests may set options.analysisMode to one of:

• AUTO: use the fast model first and fall back to the accurate model when the result is incomplete.
• FAST: use the low-latency model only.
• ACCURATE: use the high-accuracy model only.

Existing workflows without this option are treated as AUTO.