sound4/bigvoice repository overview

This is the SOUND4 BIG VOICE.CL⁠ processing.

It needs a SOUND4 license to work.

You can provide audio with RTP, and get it back with RTP.

It embeds a web server for setting up the processing.

⁠Usage

You need to define the following environment variables:

• ACCESS_KEY_ID : SOUND4 license AccessKeyID
• ACCESS_KEY_SECRET : SOUND4 license AccessKeySecret
• RADIO_NAME : SOUND4 license RadioName
• S4LOGINKEY : SOUND4 license LoginKey

⁠Storage

The process needs a storage mounted to /usr/share/sound4proc to save its state and presets.

⁠Parameters

The following variables are optional:

• RTP_SRC_PORT : the port of the audio, which you send to this container (default: 5004)
• RTP_DEST_IP : where to send the processed audio. If 0 send back to the sender (default: 0)
• RTP_DEST_PORT: the port to which you want to send the processed audio (default: 5004)
• RTP_SAMPLE_FORMAT : the audio sample format (S16_LE, S16_BE, S24_LE, S24_BE, S32_LE, S32_BE, F32_LE, F32_BE) (default: S16_BE)
• RTP_PAYLOAD : the RTP payload type (default: 96; 97 also accepts 96)
• RTP_FRAMES : the number of frames per RTP packet. 0 to send as many as received (default: 0)
• RTP_CHANNELS : the number of channels per RTP packet. The BigVoice is mono but supports stereo in/out (default: 1)

If you want to setup authentication for user interface access, you have two solutions :

1. Creating a setup account
   The setup account can create an administrator.
   The setup account always keeps the access and can delete the administrator.

   • SETUP_USER : create the setup user
   • SETUP_SECRET : the setup user's password.
     If not given, it will be randomly generated and printed in logs

2. Creating an admin account
   The administrator will be the sole administrator.

   • ADMIN_USER : create the admin user
   • ADMIN_SECRET : the admin user's password.
     If not given, it will be randomly generated and printed in logs

Once the storage is created, you can not change those.

⁠Advanced Usage

⁠Sharing storage

You can share the presets and authentication using the same storage folder for multiple instances.

In this case, you should use a different state file name, so each instance may have different settings and on-air preset. For this, you need to add the command line argument -N instancename.

If you want the instances to always have the same on-air preset, you need to add the command line argument -O onairname. All instances having the same onairname will be synchronized.

⁠Kubernetes deployment

If you use replicas in a Kubernetes cluster, you can use a Leader Election algorithm to always have a single instance really processing, keeping the others in a wait state.

To use Leader Election, you need to define:

• LEADERELECTION_LEASENAME: a unique name for the lease
• LEADERELECTION_NAMESPACE: the lease namespace
• Optional:
  • LEADERELECTION_IFACE_IP : define lease ID with this interface IP instead of hostname
  • LEADERELECTION_WAITFORCREATE : block before creating instance instead of after
  • LEADERELECTION_LEASEDURATION : lease duration
  • LEADERELECTION_RENEWDEADLINE : lease renew deadline
  • LEADERELECTION_RETRYPERIOD : lease retry period

Durations are Go duration strings, like 3s, 100ms, ...

If LEADERELECTION_WAITFORCREATE is used, the ports for HTTP and JSON will be redirected to the leader.

The pod needs access to apiGroups 'coordination.k8s.io' resources 'leases' for 'get', 'update', 'list' (and 'create' if not pre-created).

⁠Example Docker-compose.yml

services:
  process:
    image: sound4/bigvoice:${IMAGE_VERSION:-latest}
    restart: unless-stopped
    ports:
     - "${RTP_SRC_PORT:-5004}:${RTP_SRC_PORT:-5004}/udp"
     - "${HTTP_PORT:-80}:80"
    volumes:
     - state:/usr/share/sound4proc
    environment:
      # IDs for the licence SOUND4 gave you
      - S4LOGINKEY=${S4LOGINKEY}
      - RADIO_NAME=${RADIO_NAME}
      - ACCESS_KEY_ID=${ACCESS_KEY_ID}
      - ACCESS_KEY_SECRET=${ACCESS_KEY_SECRET}
      # RTP/UDP listening specific IP (use for broadcast) or Livewire channel in
      # use 0 to receive directly RTP (no Livewire)
      - RTP_SRC_IP=${RTP_SRC_IP:-0}
      - RTP_SRC_PORT=${RTP_SRC_PORT:-5004}
      # Send back to this IP or Livewire channel
      - RTP_DEST_IP=${RTP_DEST_IP}
      - RTP_DEST_PORT=${RTP_DEST_PORT:-5004}
      # verbose level: -v is 1, -vv is 2...
      - PROC_VERB=${PROC_VERB:--vv}
      # Choose sample format in S16_LE, S16_BE, S24_LE, S24_BE, S32_LE, S32_BE, F32_LE, F32_BE
      - RTP_SAMPLE_FORMAT=${RTP_SAMPLE_FORMAT:-S16_BE}
      # receive/send RTP payload. NOTE: payload 97 allows to receive payload 96 or 97, to ease compatibility.
      - RTP_PAYLOAD=${RTP_PAYLOAD:-97}
      # Audio frames Per Output Packet (default: same as received)
      - RTP_FRAMES=${RTP_FRAMES}
      # Audio channels. The BigVoice is mono but supports stereo in/out
      - RTP_CHANNELS=${RTP_CHANNELS:-1}
      # Setup/Admin user for web interface: only on storage creation
      - SETUP_USER=${SETUP_USER:-}
      - SETUP_SECRET=${SETUP_SECRET:-}
      - ADMIN_USER=${ADMIN_USER:-}
      - ADMIN_SECRET=${ADMIN_SECRET:-}
volumes:
  state: