Session Transcriptions

What is a Transcript?

A Transcript is a text version of all the words spoken during a session, for all users, combined together with additional metadata such as timestamps and user information to provide a permanent record of what was said and when. It can be used for record-keeping or as input into other systems.

Here is an example of a Lessonspace transcription:

[
  {"start_time": 26.18699993133545, "end_time": 27.38699993133545, "user": {"id": 3697650, "name": "Kitti"}, "breakout_id": "main", "text": "Hello, how are you doing."},
  {"start_time": 27.38699993133545, "end_time": 37.21699993133545, "user": {"id": 3697650, "name": "Student"}, "breakout_id": "main", "text": "I'm fine, thank you and you."},
]

For billing purposes, we work on a per-transcribed participant minute (ptpm) basis. 1 ptpm equates to one minute of audio processed per person in the session.

When does Lessonspace generate a session transcript?

You can transcribe a Session by:

• selecting the option "Allow transcription of sessions" under your Settings, or

• by providing specific values via the Launch API, as we'll describe below.

Only eligible Sessions will be transcribed. An eligible Session is any Session that:

• lasts more than 300 seconds
• and has more than one user in it

If a Session is not eligible, it will not be transcribed, even if transcription was requested.

How long does Lessonspace keep a session transcript?

Transcripts obey the same storage rules as recordings. Whenever a recording is removed, th relevant transcription will also be removed.

Enabling Transcriptions

Automatic Transcription

You can toggle transcriptions on the Addons section of your Settings dashboard to automatically transcribe sessions.

Launch API

Session transcription is set for spaces made (or updated) via the Launch API by passing the transcribe field as a boolean.

Sample Request Body

{
  "id": "your-space-id",
  "transcribe": true,
  "record_av": true,   // Only needed if AV recording is disabled for the org
  "user": {
    "name": "Teddy Transcriber"
  }
}

Example Response

{
  "client_url": "...",
  "api_base": "...",
  "room_id": "...",
  "secret": "...",
  "session_id": "...",
  "user_id": 3077485,
  "room_settings": {
    "record_av": true,
    "record_content": true,
    "waiting_room": false,
    "transcribe": true  // This indicates that transcription is now turned on for the room
  }
}

You can use the room_settings object in the response to verify whether transcription is enabled for a space.

Accessing Transcripts

You can access transcriptions in two ways, either via the Lessonspace Dashboard or via the Lessonspace API.

The Lessonspace Dashboard

Located on the Lessonspace dashboard, on the Sessions page, under the “More Actions” menu for each session.

The Download Transcription option will only be listed in the menu once the transcript has been generated, and only for sessions both originally flagged for transcription and also valid to be transcribed based on the length and number of participants.

The Lessonspace API

Transcripts can be retrieved programmatically for an individual session by performing a GET request with the session UUID in the query parameter to the transcript endpoint.

Response

Once the transcription process is complete, the response will contain a pre-signed AWS S3 download URL in the transcriptionUrl field. If the process is still ongoing, an error will be returned. URLs will be valid for 12 hours, after which you will need to repeat the API call to receive a new link.

{ "transcriptionUrl": "<pre-signed S3 URL>" }

Webhooks

It is possible to subscribe to a webhook to be notified the moment a session’s transcript is ready. You can read more about implementing webhooks generally in our documentation.

You define the webhook in the API call:

{
  "id": "your-space-id",
  "transcribe": true,
  "record_av": true,
  "user": {
    "name": "Teddy Transcriber"
  },
  "webhooks": {
    "transcription": {
      "finish": "https://your.url.here"
    }
  }
}

The webhook payload will be of the form:

{
  "room": { "id": string },
  "session": { "id": string },
  "transcriptionUrl": "<pre-signed S3 URL>"
}

Note that the links provided via webhook are valid for 24 hours.

Transcription Output Format

The downloaded JSON has the following structure. It is an array with multiple items.

[
    {
      "start_time": number,
      "end_time": number,
      "user": {
      "id": number,
      "name": string,
    },
    "breakout_id": string,
    "text": string
    }
]

• start_time: number of seconds since session start for this segment.
• end_time: number of seconds since session start for this segment.
• user.id: the Lessonspace user ID, matching the user_id returned in the Launch call and the ID in the payload for relevant webhooks.
• user.name: the user’s displayName.
• breakout_id: the string main if the user was in the main room, or a UUID if the user was in a breakout room. Users may appear to be speaking over one another or conversing nonsensically if you do not account for breakout separation.
• text: the transcribed text for this segment.

Known Limitations

• Due to the merging of multiple independent audio streams, timestamps for users may be very slightly offset, such that it sometimes appears that someone responded to a question before it was spoken.
• The audio at the very start of a session may falsely detect speech, especially if the audio begins with a prolonged period of silence.