Skip to main content

Installing mod_audio_stream

The mod_audio_stream module for FreeSWITCH is designed to stream audio content from FreeSWITCH in L16 audio format from a channel to a websocket endpoint. It uses ixwebsocket, C++ library for websocket protocol which is compiled as a static library.

This module is provided by amigniter/mod_audio_stream.

info

The mod_audio_stream module can be integrated into your existing FreeSWITCH installation allowing you to add audio streaming capabilities without disrupting or altering your existing FreeSWITCH configuration.

Installation Steps​

  • Clone the Git Repository:

    git clone https://github.com/amigniter/mod_audio_stream.git

  • Navigate to the Cloned Repository Directory:

    cd mod_audio_stream/

  • Execute following commands to initialize Git submodules:

    git submodule init
    git submodule update

    It allows the installer to link the statically compiled ixwebsocket library during the module compilation and installation process.

  • If you built FreeSWITCH from source, eq. install dir is /usr/local/freeswitch, add path to pkgconfig:

    export PKG_CONFIG_PATH=/usr/local/freeswitch/lib/pkgconfig

  • Execute following commands to build and install the module:

    mkdir build && cd build
    cmake -DCMAKE_BUILD_TYPE=Release ..
    make
    sudo make install

Verifying Installation​

To ensure FreeSWITCH loads the mod_audio_stream module, you need to manually configure it, as it will not load by default.

  1. Edit the FreeSWITCH Modules Configuration File:

    Open the configuration file with your preferred editor:

    vim /etc/freeswitch/autoload_configs/modules.conf.xml

    Add the following line to enable the module:

    <load module="mod_audio_stream" />

  2. Manually Load the Module (Optional):

    You can also manually load the module using the FreeSWITCH CLI:

    fs_cli -x 'load mod_audio_stream'

Verifying Module Installation​

To confirm that the mod_audio_stream module is installed and loaded correctly, you can use the following commands:

  • Check if the Module is Installed

    fs_cli -x 'module_exists mod_audio_stream'

    This command returns true if the module is installed, and false otherwise.

  • Show Module Details

    fs_cli -x 'show module mod_audio_stream'

    This command provides details about the module, including syntax and usage examples.

Usage Example​

Commands​

This Freeswitch module provides the following API commands:

uuid_audio_stream <uuid> start <wss-url> <mix-type> <sampling-rate> <metadata>

Attaches a media bug and starts streaming audio (in Linear16 format) to the websocket server. FS default is 8k. If sampling-rate is other than 8k it will be resampled.

  • uuid: Unique identifier of the Freeswitch channel.

  • wss-url: websocket url ws:// or wss://

  • mix-type:

    • mono: single channel containing caller's audio

    • mixed: single channel containing both caller and callee audio

    • stereo: two channels with caller audio in one and callee audio in the other.

  • sampling-rate:

    • 8k: 8000 Hz sample rate will be generated
    • 16k: 16000 Hz sample rate will be generated

  • metadata: (optional) a valid utf-8 text to send. It will be sent the first before audio streaming starts.

uuid_audio_stream <uuid> send_text <metadata>

Sends a text to the websocket server. Requires a valid utf-8 text.

uuid_audio_stream <uuid> stop <metadata>

Stops audio stream and closes websocket connection. If metadata is provided it will be sent before the connection is closed.

uuid_audio_stream <uuid> pause

Pauses audio stream

uuid_audio_stream <uuid> resume

Resumes audio stream

Events​

Module will generate the following event types:

  • mod_audio_stream::json
  • mod_audio_stream::connect
  • mod_audio_stream::disconnect
  • mod_audio_stream::error
  • mod_audio_stream::play