Audio Recording

Telemed supports recording audio from video calls. When enabled, the audio from a meeting is automatically captured, processed, and stored in Z3 as an MP4 file. A FHIR DocumentReference (opens in a new tab) is created to link the recording to the Encounter, making it discoverable through the FHIR API.

Audio recording is disabled by default and must be explicitly enabled per meeting. Only audio is captured — video and screen-sharing content are not recorded.

How it works

When you create a meeting with recordAudio: true, the system manages the full recording lifecycle automatically:

1. Meeting created — A recording is requested and queued for the meeting.
2. First attendee joins — An audio capture pipeline starts recording.
3. All attendees leave — The capture pipeline stops.
4. Meeting ends — The captured audio chunks are concatenated into a single MP4 file.
5. File transferred — The concatenated audio file is uploaded to a Z3 bucket.
6. DocumentReference created — A FHIR DocumentReference is created linking the recording to the Encounter.
7. Temporary files cleaned up — Intermediate files are removed from temporary storage.

Enabling audio recording

To record audio, pass recordAudio: true in the body of the Create Meeting request.

import Oystehr from '@oystehr/sdk';
 
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
 
const response = await oystehr.telemed.createMeeting({
  encounter: {
    resourceType: 'Encounter',
    status: 'arrived',
    class: {
      system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode',
      code: 'HH',
      display: 'home health',
    },
    participant: [
      {
        individual: {
          reference: 'Practitioner/f1d01874-0631-4903-8b32-73b3299b3363',
          display: 'Dr Adam Careful',
        },
      },
    ],
    period: {
      start: new Date().toISOString(),
    },
  },
  recordAudio: true,
});

No changes are needed on the client side for joining or leaving the meeting. Once recordAudio is set to true, the recording lifecycle is handled entirely by Oystehr.

Recording mechanism

Oystehr uses the AWS Chime SDK media capture pipeline to record audio. In order to record audio, this pipeline adds a bot to the meeting. If the UI of your client application shows attendees in the meeting, you may potentially want to hide/filter out this bot to keep the UI cleaner. You can do this using its attendee external id:

attendee.externalUserId.includes('MediaPipeline')

Alternatively, you can also use this condition to indicate the actual recording status in your custom way (bot is present -> recording is active).

Accessing the recording

After the meeting ends and processing completes, the audio recording is available in a Z3 TelemedRecordings bucket as an MP4 file. The object path follows the pattern:

{meetingUuid}/audio.mp4

You can download the recording by requesting a presigned URL from Z3:

const presignedUrl = await oystehr.z3.getPresignedUrl({
  action: 'download',
  bucketName: 'TelemedRecordings',
  'objectPath+': `${meetingUuid}/audio.mp4`,
});
 
// Use presignedUrl.signedUrl to download the file

For more details on working with Z3, see the Z3 documentation.

Also, even though you need a presigned URL to download the file, you can find its location using the FHIR API. A DocumentReference (opens in a new tab) resource is created automatically when the recording is ready. It links the audio file to the Encounter and can be found using a FHIR search:

const results = await oystehr.fhir.search({
  resourceType: 'DocumentReference',
  params: [
    { name: 'encounter', value: `Encounter/${encounterId}` },
    { name: 'type', value: 'http://loinc.org|56444-3' },
  ],
});

The DocumentReference has the following structure:

{
  "resourceType": "DocumentReference",
  "status": "current",
  "docStatus": "final",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "56444-3",
        "display": "Healthcare communication Document"
      }
    ]
  },
  "content": [
    {
      "attachment": {
        "url": "https://project-api.zapehr.com/v1/z3/TelemedRecordings/{meetingUuid}/audio.mp4",
        "contentType": "audio/mp4",
        "title": "Audio recording of the meeting"
      }
    }
  ],
  "context": {
    "encounter": [
      {
        "reference": "Encounter/{encounterId}"
      }
    ]
  }
}

The content[0].attachment.url is a Z3 URL. To download the file, request a presigned download URL from Z3 using this path.

Recording states

The recording goes through the following states during its lifecycle:

Under normal operation, the recording transitions through requested → active → recorded → committed and then the file is uploaded to Z3.

Compliance

Audio recordings may contain Protected Health Information (PHI). Ensure that your use of audio recording complies with applicable regulations, including HIPAA. Oystehr stores recordings in Z3, which is covered under Oystehr's BAA. Access to recordings is controlled by Z3 Access Policies.