Skip to main content

Recordings

Fishjam Cloud supports recording WebRTC calls encoded with H264 to HLS. All multimedia streams are composed together to create a single HLS stream and pushed to the specified AWS S3 bucket.

info

Feature is not generally available and is disabled for users by default. Users without permissions do not see anything related to this feature. For more information contact us via email contact@fishjam.io.

AWS Configuration​

To allow Fishjam Cloud to push files to your S3 bucket, you will need to create the following resources:

S3 bucket​

To create an S3 bucket follow the AWS documentation.

IAM role​

To give Fishjam Cloud access to the S3 bucket, you will need to create an IAM role with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::{YOUR_BUCKET_NAME}/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::{YOUR_BUCKET_NAME}"
            ]
        }
    ]
}

Additionally, you will need to attach the following trust policy to this role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "AWS": "339713068216"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "{YOUR_FISHJAM_CLOUD_ACCOUNT_UUID}"
                }
            }
        }
    ]
}
info

You can find {YOUR_FISHJAM_CLOUD_ACCOUNT_UUID} in the top-right corner of the Fishjam Cloud dashboard under the profile icon. It has the format of 12345678-1234-1234-1234-123456789123.

info

339713068216 is the Fishjam Cloud AWS account ID - it must be used as-is in this trust policy.

Copy the ARN of the role you created, as you will need it to configure the recording settings later.

You can find additional details about IAM roles with external IDs in the AWS documentation.

Cluster configuration​

To enable the recording feature, go to the Fishjam Cloud dashboard and select the cluster you want to configure. Then, click the Recording settings button in the top-right corner.

Recording settings

Here, you can configure the following settings:

  • Bucket name - the name of your S3 bucket where the recordings will be stored
  • Bucket region - the region of your S3 bucket
  • Role ARN - the ARN of the IAM role you created
  • Base path - the subpath in the S3 bucket where the further directories will be created for storing recordings. No keys without this prefix will be created in your bucket.

Testing the settings​

Before confriming your settings which results in restarting all active instances within the cluster you can check if they are working using Test button. The test itself tries to upload fishjam-test-file.json to the bucket in the provided base path.

In case of failure the possible root cause is highlighted like in the example below.

recording_test_failed

If provided settings allowed to upload the file the green checkmark appears near the button.

recording_test_succeeded

Recording flow​

This section provides an overview of the end-to-end recording flow in Fishjam Cloud.

API request​

To start recording a call, you need to send a request to the Fishjam server that will create a RecordingComponent. To view the API details, go to the Fishjam API documentation and choose the ComponentOptionsRecording in the request schema.

Here is an example request:

curl --request POST \
  --url <https://cloud.fishjam.work/api/v1/jellyfish/manage/c07e5964f8454216987bdd4acb440ae0/8e611249c6f64abaa20ab047d86b5fbc/room/82/component> \
  --header 'Authorization: Bearer 54e4b106585c4dc291f16532d0ceff4f' \
  --header 'Content-Type: application/json' \
  --data '{
 "type": "recording"
}'
info

Do not provide any S3 bucket credentials or the pathPrefix in the request body. The recording component will use the settings provided by Fishjam Cloud to process the request, and the resulting HLS stream will be pushed to the S3 bucket specified in the cluster settings.

The only thing that can be configured in the request body is the optional subscribeMode parameter.

The response will contain the id of the created RecordingComponent that you can use to stop the recording by using the delete component endpoint.

For more detailed information, see the Recording component documentation.

Processed HLS stream​

After the recording has ended, either by stopping the recording or by the end of the call, the HLS stream will begin processing. The processing time depends on the length of the recording and the number of streams that need to be processed. After the processing, the HLS stream will be pushed to the S3 bucket specified in the cluster settings.

E.g., if the base path is set to recordings, the HLS index file will be pushed to s3://<bucket-name>/recordings/<room-id>/<recording-id>/index.m3u8.

tip

To view the HLS stream on your machine, you can download the whole directory from the S3 bucket and convert it with ffmpeg to a single file with the following command:

ffmpeg -i "index.m3u8" -acodec copy -vcodec copy out.mp4