​

Cloud recording: Quickstart

With cloud recording, you can record audio for a channel and save it to cloud storage. This feature works with all Aircore SDKs that support audio.

You use a REST API to start and stop recording. Aircore uploads recordings as .m4a files with AAC encoding.

Before starting

Start recording

To start recording, send a request like the one below.

Use a unique value for one of the following:

  • filename: This is a prefix for the filename of the recording. You can use a unique prefix to find the file in your S3 bucket.

  • callback_url: Provide this to receive updates on the recording. When a recording is uploaded, you receive a link to the file.

Request

curl -X POST "https://services.aircore.io/recording" \
-H "Authorization: Bearer SECRET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "storage": {
    "filename": "record",
    "s3": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "bucket": "S3_BUCKET_NAME",
      "region": "us-east-1",
      "server_side_encryption": "AES256"
    }
  },
  "location": {
    "latitude": 40.785091,
    "longitude": -73.968285
  },
  "user_id": "4a1c5943-994e-4c2b-a717-7f6ff42c5396",
  "channel_id": "9a01c703-48db-4101-ad8a-c907f04f0c3a",
  "callback_url": "https://your_server.com/recordings?id=2348723149"
}'

Response

{
  "url": "https://services.aircore.io:443/recording/http%3A%2F%2Fvandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com%3A8080%2Frecording%2F1677608374942-0-503309",
  "state": "started",
  "startTime": 1665460533516,
  "elapsedTime": 0
}

Use the URL in this response to send the next request.

See the full API reference: Start recording.

Stop recording

To stop recording, use the URL from the previous response to send a request like the one below.

curl -X DELETE "https://services.aircore.io:443/recording/http%3A%2F%2Fvandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com%3A8080%2Frecording%2F1677608374942-0-503309" \
-H "Authorization: Bearer SECRET_API_KEY" \

The recording is automatically uploaded to S3. Recording also stops automatically if all users leave the channel.

See the full API reference: Stop recording.

Find a recording

You can find a recording using the filename or with callbacks. This depends on the request to start recording.

If you provided a unique prefix for the filename:

  • Check your S3 bucket for the recording. The filename string is the first part of the filename.

If you provided a unique URL for callbacks:

  • Use the link in the callback you receive when the recording is uploaded.

The callback for a successful recording looks like this. The link to the file is in the address field:

{
  "event": "recording-uploaded",
  "timestamp": 1677023448142,
  "recording": {
    "url": "http://vandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com:8080/recording/1677608374942-0-503309",
    "state": "stopped",
    "startTime": 1665460533516,
    "elapsedTime": 11115,
    "location": {
      "address": "https://youraccount.s3.amazonaws.com/record_1677608374942-0-503309.m4a",
      "region": "us-east-1"
    }
  }
}

For the full API reference, see the Callbacks section in Start recording.