Compile and run the sample project

Updated

Set up, compile, and run the sample Server Gateway project provided by Agora.

Agora provides a runnable sample project on GitHub. This page shows you how to clone and run the project to send and receive media streams.

To clone the repository, run the following command:

git clone -b release/2.2.4 https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK.git

The sample projects are in the agora_rtc/examples folder. This page shows you how to run the example_audio_pcm_send and example_audio_pcm_receive projects.

The examples folder contains the following files:

.
└── agora_rtc
    └── examples
        ├── common  # Common components
        │   ├── __init__.py
        │   ├── audio_consumer.py
        │   ├── example_base.py
        │   ├── pacer.py
        │   ├── parse_args.py
        │   ├── path_utils.py
        │   ├── push_audio_encoded_file.py
        │   ├── push_audio_pcm_file.py
        │   ├── push_video_encoded_file.py
        │   └── push_video_yuv_file.py
        ├── example_agora_parameter.py  # Set private parameters
        ├── example_audio_encoded_receive.py  # Receive encoded audio data
        ├── example_audio_encoded_send.py  # Send encoded audio data
        ├── example_audio_pcm_loopback.py  # Loopback test
        ├── example_audio_pcm_receive.py  # Receive raw audio data
        ├── example_audio_pcm_receive_and_send.py  # Send and receive raw audio data
        ├── example_audio_pcm_send.py  # Send raw audio data
        ├── example_pcm_yuv_receive.py  # Receive raw video and audio data
        ├── example_pcm_yuv_send.py  # Send raw video and audio data
        ├── example_pcm_yuv_send_receive.py  # Send and receive raw video and audio data
        ├── example_stream_message_receive.py  # Receive stream messages
        ├── example_stream_message_send.py  # Send stream messages
        ├── example_video_encoded_receive.py  # Receive encoded video data
        ├── example_video_encoded_send.py  # Send encoded video data
        ├── example_video_yuv_receive.py  # Receive YUV video data
        ├── example_video_yuv_send.py  # Send YUV video data
        └── observer  # Event listeners
            ├── audio_frame_observer.py
            ├── connection_observer.py
            ├── local_user_observer.py
            ├── video_encoded_frame_observer.py
            └── video_frame_observer.py

Run the server streaming sample

To run the example_audio_pcm_send sample project, take the following steps:

  1. To send PCM audio, run the example_audio_pcm_send project. Change the parameter values as needed:

    python agora_rtc/examples/example_audio_pcm_send.py \
    --appId=0a****************************99 \
    --channelId=test_example \
    --userId=6 \
    --audioFile=./test_data/demo.pcm \
    --sampleRate=16000 \
    --numOfChannels=1

    The parameters are as follows:

    • appId: The App ID of your Agora project.
    • channelId: The channel name.
    • userId: Your user ID.
    • audioFile: The path to the audio file. For testing, you can download Agora's test data and decompress it to the Agora-Python-Server-SDK folder.
    • sampleRate: The audio sample rate.
    • numOfChannels: The number of audio channels.
  2. When the server connects to the channel, the terminal shows output similar to the following:

    INFO:common.parse_args:Parsed arguments:Namespace(appId='0a****************************99', token=None, channelId='test_example', connectionNumber='1', userId='6', audioFile='./test_data/demo.pcm', lowdelay=False, videoFile=None, sampleRate=16000, numOfChannels=1, fps=None, width=None, height=None, bitrate=None, message=None, hours='0', mode=1, value=0)
    INFO:common.example_base:------channel_id: test_example, uid: 6
    INFO:common.example_base:connect_and_release: 0, auto_subscribe_audio: 0
    INFO:observer.connection_observer:on_connecting, agora_rtc_conn=<agora.rtc.rtc_connection.RTCConnection object at 0x103c173d0>, local_user_id=0, state=2, internal_uid=0 ,reason=0
    INFO:observer.connection_observer:on_connected, agora_rtc_conn=<agora.rtc.rtc_connection.RTCConnection object at 0x103c173d0>, local_user_id=3997884694, state=3, internal_uid=0 ,reason=1
  3. When the server sends PCM audio, the terminal shows output similar to the following:

    INFO:common.push_audio_pcm_file:send pcm: count,ret=1, 0, 3200, 0.1
    INFO:common.push_audio_pcm_file:send pcm: count,ret=2, 0, 3200, 0.1
    ...

To simulate a client that receives the PCM audio in a browser, use the Agora Web demo:

  1. Open the Web demo and fill in the initialization settings. Use the same App ID as the server.

  2. Select Basic Voice Calling, enter the channel name that you passed to channelId in Channel, then click Create Client and Join Channel.

  3. When a user in the channel publishes a stream, the Web demo fills in that user's ID under Step 4 Subscribe & Play. Click Subscribe & Play to subscribe to the stream.

    Join the channel in the Web demo before you run the sample project on the server. Otherwise, the Web demo doesn't fill in the user ID under Step 4 Subscribe & Play and can't subscribe to the server's stream.

  4. After you subscribe, you hear the audio, and the Web demo shows the user ID of the stream under Remote Stream:.

Run the server receiving sample

To run the example_audio_pcm_receive sample project, take the following steps:

  1. To receive PCM audio, run the example_audio_pcm_receive project. Change the parameter values as needed:

    python agora_rtc/examples/example_audio_pcm_receive.py \
    --appId=0a****************************99 \
    --channelId=test_example \
    --userId=8 \
    --sampleRate=16000 \
    --numOfChannels=1

    The parameters are as follows:

    • appId: The App ID of your Agora project.
    • channelId: The channel name.
    • userId: Your user ID.
    • sampleRate: The audio sample rate.
    • numOfChannels: The number of audio channels.
  2. When the server connects to the channel, the terminal shows output similar to the following:

    INFO:common.parse_args:Parsed arguments:Namespace(appId='0a****************************99', audioFile=None, bitrate=None, channelId='test_example', connectionNumber='1', fps=None, height=None, hours='0', lowdelay=False, message=None, numOfChannels=1, sampleRate=16000, token=None, userId='8', videoFile=None, width=None)
    INFO:common.example_base:------channel_id: test_example, uid: 8
    INFO:observer.connection_observer:on_connecting, agora_rtc_conn=<agora.rtc.rtc_connection.RTCConnection object at 0x7f419d81f4a8>, local_user_id=6, state=2, internal_uid=0 ,reason=0
    # Successfully connected to the channel
    INFO:observer.connection_observer:on_connected, agora_rtc_conn=<agora.rtc.rtc_connection.RTCConnection object at 0x7f419d81f4a8>, local_user_id=6, state=3, internal_uid=0 ,reason=1
  3. To simulate a client that sends PCM audio from a browser, open the Agora Web demo and fill in the initialization settings. Use the same App ID as the server.

  4. Select Basic Voice Calling, enter the channel name that you passed to channelId in Channel, then click Create Client and Join Channel. When the Web demo joins the channel, the terminal shows output similar to the following:

    INFO:observer.connection_observer:on_user_joined, agora_rtc_conn=<agora.rtc.rtc_connection.RTCConnection object at 0x7f419d81f4a8>, user_id=45
    INFO:observer.local_user_observer:on_user_info_updated, user_id=45, msg=0,val=1
    INFO:observer.local_user_observer:on_user_info_updated, user_id=45, msg=4,val=1
  5. In the Web demo, click Create Track & Publish to publish the stream. When the server receives the audio, the terminal shows output similar to the following:

    INFO:observer.audio_frame_observer:on_playback_audio_frame_before_mixing, channelId=test_dys1, uid=45, type=0, samples_per_sec=16000, samples_per_channel=160, bytes_per_sample=2, channels=1, len=320
    INFO:observer.audio_frame_observer:on_playback_audio_frame_before_mixing, file_path=/home/agora/Documents/Agora-Python-Server-SDK-dev-2.0/logs/audio_frame_observer/2024_09_27_17_46_37/test_dys1_45.pcm, len=320

    Connect the server to the channel before the Web demo joins and publishes. Otherwise, the server can't receive the audio stream from the Web demo.