Forem: Vikram Vaswani

Build a Speech-to-Text Web Application with Rev AI and PHP (Part 2)

Vikram Vaswani — Mon, 26 Sep 2022 14:00:24 +0000

By Vikram Vaswani, Developer Advocate
This tutorial was originally published at https://docs.rev.ai/resources/tutorials/build-speech-to-text-web-application-php-2/ on Sep 08, 2022.

Introduction

Rev AI's automatic speech recognition (ASR) APIs enable developers to integrate fast and accurate speech-to-text capabilities into their applications. The first part of this tutorial introduced you to Rev AI's Asynchronous Speech-to-Text API. It explained how to record audio through a Web browser and submit the audio to Rev AI for transcription via the API using the Guzzle PHP HTTP client.

At the end of the first part of this tutorial, the example application was able to submit audio to Rev AI, but you still had to use the Rev AI dashboard to manually retrieve your transcripts. This concluding segment closes the loop, explaining how to retrieve transcripts from Rev AI using a webhook and display them in the example application. It will also explain how to add transcript deletion and search functions to the Web application.

NOTE: The complete source code for the example application is available on GitHub, so you can download and try it immediately.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have Docker installed. If not, download and install Docker for your operating system.
You have Docker Compose installed. If not, install Docker Compose for your operating system.
You will deploy the application's webhook at a public URL. If not, or if you prefer to develop and test locally, download and install ngrok and obtain an ngrok authentication token. You will need this to generate a temporary public URL for the webhook.

Any application that uses the Rev AI APIs must also comply with Rev AI's API limits and terms of service. Before proceeding, please review these documents and ensure that you are in agreement with them.

NOTE: This tutorial uses a Docker-based Apache/PHP/MongoDB development environment. If you already have a properly-configured development environment with Apache 2.x, PHP 8.1.x with the MongoDB extension and Composer, you can use that instead. You may need to replace some Docker commands with equivalents.

Step 1: Receive transcripts from Rev AI using a webhook

Once a job is submitted to Rev AI for asynchronous transcription via the API, there are three ways to know when transcription is complete. You can check job status via the Rev AI Web dashboard; you can repeatedly poll the API for status; or you can let Rev AI notify you automatically via a webhook. Of these three options, using a webhook is the most efficient approach.

NOTE: If you're not familiar with webhooks, refer to our tutorial on getting started with Rev AI webhooks for more information. You can also learn how to use Rev AI webhooks to automatically send email notifications when a job completes, or how to retrieve final transcripts via the API and save them to a MongoDB database.

To let Rev AI know that it should use a webhook, including the notification_config parameter in the request to the Asynchronous Speech-to-Text API endpoint at https://api.rev.ai/speechtotext/v1/jobs, as shown below:

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "source_config": {"url": "https://www.rev.ai/FTC_Sample_1.mp3"},
       "notification_config": {"url": "https://example.com/my/webhook"}
      }'

Once the job is complete, the API will make an HTTP POST request to the specified URL with a JSON document in the POST request body. Here is an example of the POST request body:

{
  "job": {
    "id": "8xBckmk6rAqu",
    "created_on": "2022-08-16T14:26:14.151Z",
    "completed_on": "2022-08-16T14:26:53.601Z",
    "name": "FTC_Sample_1.mp3",
    "notification_config": {"url": "https://example.com/my/webhook"},
    "source_config": {"url": "https://www.rev.ai/FTC_Sample_1.mp3"},
    "status": "transcribed",
    "duration_seconds": 107,
    "type": "async",
    "language": "en"
  }
}

From the above discussion, it should be clear that there are two steps involved when integrating a Rev AI webhook into an application:

At job submission time, include a webhook URL in the notification_config parameter of the job request.
Define a webhook URL handler that is able to receive the HTTP POST request, parse the request body and take further action (such as retrieving the transcript) based on the received data.

NOTE: In order to receive notifications from Rev AI, the webhook URL must be a publicly-accessible URL. When developing and testing locally, this may not always be possible. For such situations, use ngrok to create a temporary public URL that will serve as the webhook URL.

Make the changes as described below:

Update the config/settings.php file with an additional configuration key for the webhook URL.
```
<?php
return [
    'rev' => [
        'token' => '<REVAI_ACCESS_TOKEN>',
        'callback' => '<CALLBACK_PREFIX>/hook',
    ],
    'mongo' => [
        'uri' => '<MONGODB_URI>'
    ]
];
```
If you are deploying the application at an existing public URL, replace the <CALLBACK_PREFIX> placeholder with the application URL.

If you are developing and testing locally without a publicly-accessible URL, first create and obtain a temporary webhook URL with ngrok and then replace the <CALLBACK_PREFIX> placeholder in the config/settings.php file with that temporary URL.
Update the front controller at public\index.php with the following changes:

Update the POST route handler for the /add URL endpoint to include the notification_config parameter in the job request.

  <?php

  // ...

  // POST request handler for /add page
  $app->post(
      '/add',
      function (Request $request, Response $response) {
          // get MongoDB service
          // insert a record in the database for the audio upload
          // get MongoDB document ID
          $mongoClient = $this->get('mongo');
          try {
              $insertResult = $mongoClient->mydb->notes->insertOne(
                  [
                      'status' => 'JOB_RECORDED',
                      'ts'     => time(),
                      'jid'    => false,
                      'error'  => false,
                      'data'   => false,
                  ]
              );
              $id           = (string) $insertResult->getInsertedId();
              // get uploaded file
              // if no upload errors, change status in database record
              $uploadedFiles = $request->getUploadedFiles();
              $uploadedFile = $uploadedFiles['file'];
              if ($uploadedFile->getError() === UPLOAD_ERR_OK) {
                  $mongoClient->mydb->notes->updateOne(
                      [
                          '_id' => new ObjectID($id),
                      ],
                      [
                          '$set' => ['status' => 'JOB_UPLOADED'],
                      ]
                  );
                  // get Rev AI API client
                  // submit audio to API as POST request
                  $revClient   = $this->get('guzzle');
                  $revResponse = $revClient->request(
                      'POST',
                      'jobs',
                      [
                          'multipart' => [
                              [
                                  'name'     => 'media',
                                  'contents' => fopen($uploadedFile->getFilePath(), 'r'),
                              ],
                              [
                                  'name'     => 'options',
                                  'contents' => json_encode(
                                      [
                                          'metadata'         => $id,
                                          'skip_diarization' => 'true',
                                          'notification_config'     => [
                                              'url' => $this->get('settings')['rev']['callback']
                                          ],
                                      ]
                                  ),
                              ],
                          ],
                      ]
                  )->getBody()->getContents();
                  // get API response
                  // if no API error, update status in database record
                  // send 200 response code to client
                  $json        = json_decode($revResponse);
                  $mongoClient->mydb->notes->updateOne(
                      [
                          '_id' => new ObjectID($id),
                      ],
                      [
                          '$set' => [
                              'status' => 'JOB_TRANSCRIPTION_IN_PROGRESS',
                              'jid'    => $json->id,
                          ],
                      ]
                  );
                  $response->getBody()->write(json_encode(['success' => true]));
                  return $response->withHeader('Content-Type', 'application/json')->withStatus(200);
              }
          } catch (\GuzzleHttp\Exception\RequestException $e) {
              // in case of API error
              // update status in database record
              // send error code to client with error message as payload
              $mongoClient->mydb->notes->updateOne(
                  [
                      '_id' => new ObjectID($id),
                  ],
                  [
                      '$set' => [
                          'status' => 'JOB_TRANSCRIPTION_FAILURE',
                          'error'  => $e->getMessage(),
                      ],
                  ]
              );
              $response->getBody()->write(json_encode(['success' => false]));
              return $response->withHeader('Content-Type', 'application/json')->withStatus($e->getResponse()->getStatusCode());
          }
      }
  );

  // ...

Add a new handler for POST requests to the /hook webhook URL endpoint, which accepts and processes the POST request received from the Rev AI API.

  <?php

  // ...

  // POST request handler for /hook webhook URL
  $app->post(
      '/hook',
      function (Request $request, Response $response) {
          try {
              // get MongoDB service
              $mongoClient = $this->get('mongo');

              // decode JSON request body
              // obtain identifiers and status
              $json        = json_decode($request->getBody());
              $jid         = $json->job->id;
              $id          = $json->job->metadata;

              // if job successful
              if ($json->job->status === 'transcribed') {

                  // update status in database
                  $mongoClient->mydb->notes->updateOne(
                      [
                          '_id' => new ObjectID($id),
                      ],
                      [
                          '$set' => ['status' => 'JOB_TRANSCRIPTION_SUCCESS'],
                      ]
                  );

                  // get transcript from API
                  $revClient   = $this->get('guzzle');
                  $revResponse = $revClient->request(
                      'GET',
                      "jobs/$jid/transcript",
                      [
                          'headers' => ['Accept' => 'text/plain'],
                      ]
                  )->getBody()->getContents();
                  $transcript  = explode('    ', $revResponse)[2];

                  // save transcript to database
                  $mongoClient->mydb->notes->updateOne(
                      [
                          '_id' => new ObjectID($id),
                      ],
                      [
                          '$set' => ['data' => $transcript],
                      ]
                  );
              // if job unsuccesful
              } else {

                  // update status in database
                  // save problem detail error message
                  $mongoClient->mydb->notes->updateOne(
                      [
                          '_id' => new ObjectID($id),
                      ],
                      [
                          '$set' => [
                              'status' => 'JOB_TRANSCRIPTION_FAILURE',
                              'error'  => $json->job->failure_detail,
                          ],
                      ]
                  );
              }
          } catch (\GuzzleHttp\Exception\RequestException $e) {
              $mongoClient->mydb->notes->updateOne(
                  [
                    '_id' => new ObjectID($id),
                  ],
                  [
                    '$set' => [
                        'status' => 'JOB_TRANSCRIPTION_FAILURE',
                        'error'  => $e->getMessage(),
                    ],
                  ]
              );
          }
          return $response->withStatus(200);
      }
  );

  // ...

This route handler contains a lot of code, so let's step through it:

When this endpoint is invoked with a HTTP POST request, the handler first inspects the JSON document received and extracts three key pieces of information from it:

The Rev AI job identifier, which will be used to retrieve the final transcript;
The MongoDB document identifier, which serves to identify the corresponding record in the application database. Recollect that this MongoDB document identifier was included in the metadata parameter when the job was originally submitted;
The Rev AI job status, which indicates whether transcription succeeded or failed.

If the job was successful, the handler updates the document status to JOB_TRANSCRIPTION_SUCCESS. It then uses the Guzzle Rev AI API client to prepare and send a HTTP GET request to https://api.rev.ai/speechtotext/v1/jobs/<ID>/transcript to retrieve the final transcript in plaintext format. The MongoDB document is then updated, with the transcript content saved to the document's data field.

If the job was unsuccessful, the handler updates the document status to JOB_TRANSCRIPTION_FAILURE. In this case, the JSON document also includes a problem description, which is saved to the document's error field in the MongoDB database.

On completion of the above actions, the handler returns a 200 response code to the Rev AI API server.

Step 2: List transcripts in the application

Once the webhook is in place, retrieving and saving transcripts to the MongoDB database, the next step is to display them in the application user interface.

Update the GET route handler for the /index endpoint to execute a MongoDB query and return all the records in the application database. Make this change in the front controller at public/index.php.

<?php
// ...

// GET request handler for index page
$app->get(
    '/[index[/]]',
    function (Request $request, Response $response, $args) {
        $params = $request->getQueryParams();
        $mongoClient = $this->get('mongo');
        return $this->get('view')->render(
            $response,
            'index.twig',
            [
                'status' => !empty($params['status']) ? $params['status'] : null,
                'data'   => $mongoClient->mydb->notes->find(
                    [],
                    [
                        'sort' => [
                            'ts' => -1,
                        ],
                    ]
                )
            ]
        );
    }
)->setName('index');

// ...

The MongoDB result set is returned via the data Twig template variable.

Update the public/index.twig page template to loop over the result set and display the MongoDB result set as an HTML table, including transcript content, timestamp, status and Rev AI job identifier. Add a "Refresh" button to the page as part of this update, which provides a way for the user to reload the page.

{% extends "layout.twig" %}

{% block content %}
  <header class="d-flex justify-content-center py-3">
    <h1>My Notes</h1>
  </header>

  {% if status == 'submitted' %}
  <div class="alert alert-success text-center" role="alert">Audio sent for transcription.</div>
  {% endif %}

  {% if status == 'error' %}
  <div class="alert alert-danger text-center" role="alert">Audio transcription failed.</div>
  {% endif %}

  <table class="table">
    <thead class="thead-light">
      <tr>
        <th scope="col">#</th>
        <th scope="col">Date</th>
        <th scope="col">Contents</th>
        <th scope="col">Status</th>
        <th scope="col">Rev AI Job ID</th>
        <th scope="col"><a class="btn btn-primary" href="{{ url_for('index') }}" role="button">Refresh</a></th>
      </tr>
    </thead>
    <tbody>
  {% for item in data %}
    <tr>
      <td>{{ loop.index }}</td>
      <td>{{ item.ts|date("d M Y h:i e") }}</td>
      <td class="text-wrap" style="max-width: 150px;">{{ item.data }}</td>
    {% if item.status in ['JOB_UPLOADED', 'JOB_TRANSCRIPTION_IN_PROGRESS'] %}
      <td>In progress</td>
    {% elseif item.status == 'JOB_RECORDED' %}
      <td>Recorded</td>
    {% elseif item.status == 'JOB_TRANSCRIPTION_SUCCESS' %}
      <td>Transcribed</td>
    {% elseif item.status == 'JOB_TRANSCRIPTION_FAILURE' %}
      <td class="text-wrap" style="max-width: 150px;">Failed <br/> {{ item.error }}</td>
    {% endif %}
      <td>{{ item.jid }}</td>
      <td></td>
    </tr>
  {% endfor %}
    </tbody>
  </table>
{% endblock %}

This template loops over the data template variable and, for each record, displays the formatted date and time, transcript data, job status and Rev AI job identifier. Note that the template inspects the document's status field, which could be any one of JOB_RECORDED, JOB_UPLOADED, JOB_TRANSCRIPTION_IN_PROGRESS, JOB_TRANSCRIPTION_SUCCESS or JOB_TRANSCRIPTION_FAILURE, and displays a human-readable message for each, including an error message for failed jobs.

Step 3: Search for transcripts in the application

Now that you have the basics in place, it's time to add further functionality to the application. For example, users should be able to quickly search the generated transcripts and find those matching specific terms.

This can be achieved by using a MongoDB regular expression to filter the stored transcripts and return the matching ones, as described below:

Update the index page template at views/index.twig to include a simple search form, as below:

{% extends "layout.twig" %}

{% block content %}

  <!-- ... -->

  <div class="col-sm-4">
    <form class="form-inline">
      <div class="input-group">
        <input class="form-control" name="term" value="{{ term }}" placeholder="Search">
        <div class="input-group-append">
          <button class="btn btn-outline-secondary" type="submit">Go</button>
        </div>
      </div>
    </form>
  </div>

  <!-- ... -->

{% endblock %}

When this search form is submitted, the search term entered by the user is added to the URL as a query parameter.

Update the GET route handler for the /index endpoint in the front controller script public/index.php to read the submitted search term and modify the default MongoDB query with an additional regular expression filter. This change ensures that only results matching the search term are returned and displayed in the index page template.

<?php
// ...

// GET request handler for index page
$app->get(
    '/[index[/]]',
    function (Request $request, Response $response, $args) {
        $params = $request->getQueryParams();
        $condition = !empty($params['term']) ?
            [
                'data' => new MongoDB\BSON\Regex(filter_var($params['term'], FILTER_UNSAFE_RAW), 'i')
            ] :
            [];
        $mongoClient = $this->get('mongo');
        return $this->get('view')->render(
            $response,
            'index.twig',
            [
                'status' => !empty($params['status']) ? $params['status'] : null,
                'data'   => $mongoClient->mydb->notes->find(
                    $condition,
                    [
                        'sort' => [
                            'ts' => -1,
                        ],
                    ]
                ),
                'term' => !empty($params['term']) ? $params['term'] : null,
            ]
        );
    }
)->setName('index');

// ...

The route handler uses the request object's getQueryParams() method to retrieve the search term and then adds a regular expression condition to the default MongoDB search query. This condition ensures that only transcripts containing the regular expression are returned by the query. The result set is then interpolated into the index page template for display as usual.

Step 4: Delete transcripts from the application

Users should also have the option to delete voice notes which are no longer relevant through the Web application interface.

Implement this functionality as below:

Update the index page template at views/index.twig to support an additional "Delete" button for each displayed transcript and a new deleted status message, as below.

{% extends "layout.twig" %}

{% block content %}

  <!-- ... -->

  {% if status == 'deleted' %}
  <div class="alert alert-success text-center" role="alert">Note deleted.</div>
  {% endif %}

  <!-- ... -->

  <table class="table">

    <!-- ... -->

    <tbody>
  {% for item in data %}
    <tr>
      <td>{{ loop.index }}</td>
      <td>{{ item.ts|date("d M Y h:i e") }}</td>
      <td class="text-wrap" style="max-width: 150px;">{{ item.data }}</td>
    {% if item.status in ['JOB_UPLOADED', 'JOB_TRANSCRIPTION_IN_PROGRESS'] %}
      <td>In progress</td>
    {% elseif item.status == 'JOB_RECORDED' %}
      <td>Recorded</td>
    {% elseif item.status == 'JOB_TRANSCRIPTION_SUCCESS' %}
      <td>Transcribed</td>
    {% elseif item.status == 'JOB_TRANSCRIPTION_FAILURE' %}
      <td class="text-wrap" style="max-width: 150px;">Failed <br/> {{ item.error }}</td>
    {% endif %}
      <td>{{ item.jid }}</td>
      <td><a class="btn btn-danger" href="{{ url_for('delete', { 'id': item._id }) }}" role="button">Delete</a></td>
    </tr>
  {% endfor %}
    </tbody>
  </table>
{% endblock %}

Note that the generated hyperlink for each "Delete" button will point to a route named delete and will include the MongoDB document identifier as a URL parameter.

Create a GET route handler for the new /delete endpoint which accepts a MongoDB document identifier as a URL parameter. Add this route to the front controller script public/index.php.

<?php

// ...

// GET request handler for /delete page
$app->get(
    '/delete/{id}',
    function (Request $request, Response $response, $args) use ($app) {
        $id          = filter_var($args['id'], FILTER_UNSAFE_RAW);
        $mongoClient = $this->get('mongo');
        $mongoClient->mydb->notes->deleteOne(
            [
                '_id' => new ObjectID($id),
            ]
        );
        $routeParser = $app->getRouteCollector()->getRouteParser();
        return $response->withHeader('Location', $routeParser->urlFor('index', [], ['status' => 'deleted']))->withStatus(302);
    }
)->setName('delete');

// ...

This route handler reads the MongoDB document identifier, uses the MongoDB client's deleteOne method to delete the corresponding transcript from the application database and then redirects the user back to the /index URL with a success notification.

NOTE: Deleting a voice note as described in this section removes it from the application database, but does not delete it from Rev AI's servers. To do this, you must either submit a separate DELETE request via the API or include the delete_after_seconds parameter in the initial job request. To learn more, refer to the tutorial on deleting user data from Rev AI.

For reference, here is the final front controller script. Replace the public\index.php file with this version.

<?php

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
use Slim\Views\Twig;
use Slim\Views\TwigMiddleware;
use Slim\Routing\RouteContext;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7;
use DI\ContainerBuilder;
use MongoDB\BSON\ObjectID;

// load dependencies
require __DIR__ . '/https://docs.rev.ai/resources/tutorials/vendor/autoload.php';

// create DI container
$containerBuilder = new ContainerBuilder();

// define services
$containerBuilder->addDefinitions(
    [
        'settings' => function () {
            return include __DIR__ . '/https://docs.rev.ai/resources/tutorials/config/settings.php';
        },
        'view'     => function () {
            return Twig::create(__DIR__ . '/https://docs.rev.ai/resources/tutorials/views');
        },
        'mongo'    => function ($c) {
            return new MongoDB\Client($c->get('settings')['mongo']['uri']);
        },
        'guzzle'   => function ($c) {
            $token = $c->get('settings')['rev']['token'];
            return new Client(
                [
                    'base_uri' => 'https://api.rev.ai/speechtotext/v1/jobs',
                    'headers'  => ['Authorization' => "Bearer $token"],
                ]
            );
        },
    ]
);

$container = $containerBuilder->build();

AppFactory::setContainer($container);

// create application with DI container
$app = AppFactory::create();

// add Twig middleware
$app->add(TwigMiddleware::createFromContainer($app));

// add error handling middleware
$app->addErrorMiddleware(true, true, true);

// GET request handler for index page
$app->get(
  '/[index[/]]',
  function (Request $request, Response $response, $args) {
      $params = $request->getQueryParams();
      $condition = !empty($params['term']) ?
          [
              'data' => new MongoDB\BSON\Regex(filter_var($params['term'], FILTER_UNSAFE_RAW), 'i')
          ] :
          [];
      $mongoClient = $this->get('mongo');
      return $this->get('view')->render(
          $response,
          'index.twig',
          [
              'status' => !empty($params['status']) ? $params['status'] : null,
              'data'   => $mongoClient->mydb->notes->find(
                  $condition,
                  [
                      'sort' => [
                          'ts' => -1,
                      ],
                  ]
              ),
              'term' => !empty($params['term']) ? $params['term'] : null,
          ]
      );
  }
)->setName('index');

// GET request handler for /add page
$app->get(
    '/add',
    function (Request $request, Response $response, $args) {
        return $this->get('view')->render(
            $response,
            'add.twig',
            []
        );
    }
)->setName('add');

// POST request handler for /add page
$app->post(
    '/add',
    function (Request $request, Response $response) {
        // get MongoDB service
        // insert a record in the database for the audio upload
        // get MongoDB document ID
        $mongoClient = $this->get('mongo');
        try {
            $insertResult = $mongoClient->mydb->notes->insertOne(
                [
                    'status' => 'JOB_RECORDED',
                    'ts'     => time(),
                    'jid'    => false,
                    'error'  => false,
                    'data'   => false,
                ]
            );
            $id           = (string) $insertResult->getInsertedId();

            // get uploaded file
            // if no upload errors, change status in database record
            $uploadedFiles = $request->getUploadedFiles();
            $uploadedFile = $uploadedFiles['file'];

            if ($uploadedFile->getError() === UPLOAD_ERR_OK) {
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => ['status' => 'JOB_UPLOADED'],
                    ]
                );

                // get Rev AI API client
                // submit audio to API as POST request
                $revClient   = $this->get('guzzle');
                $revResponse = $revClient->request(
                    'POST',
                    'jobs',
                    [
                        'multipart' => [
                            [
                                'name'     => 'media',
                                'contents' => fopen($uploadedFile->getFilePath(), 'r'),
                            ],
                            [
                                'name'     => 'options',
                                'contents' => json_encode(
                                    [
                                        'metadata'         => $id,
                                        'notification_config'     => [
                                            'url' => $this->get('settings')['rev']['callback']
                                        ],
                                        'skip_diarization' => 'true',
                                    ]
                                ),
                            ],
                        ],
                    ]
                )->getBody()->getContents();

                // get API response
                // if no API error, update status in database record
                // send 200 response code to client
                $json        = json_decode($revResponse);
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => [
                            'status' => 'JOB_TRANSCRIPTION_IN_PROGRESS',
                            'jid'    => $json->id,
                        ],
                    ]
                );
                $response->getBody()->write(json_encode(['success' => true]));
                return $response->withHeader('Content-Type', 'application/json')->withStatus(200);
            }
        } catch (\GuzzleHttp\Exception\RequestException $e) {
            // in case of API error
            // update status in database record
            // send error code to client with error message as payload
            $mongoClient->mydb->notes->updateOne(
                [
                    '_id' => new ObjectID($id),
                ],
                [
                    '$set' => [
                        'status' => 'JOB_TRANSCRIPTION_FAILURE',
                        'error'  => $e->getMessage(),
                    ],
                ]
            );
            $response->getBody()->write(json_encode(['success' => false]));
            return $response->withHeader('Content-Type', 'application/json')->withStatus($e->getResponse()->getStatusCode());
        }
    }
);

// GET request handler for /delete page
$app->get(
    '/delete/{id}',
    function (Request $request, Response $response, $args) use ($app) {
        $id          = filter_var($args['id'], FILTER_UNSAFE_RAW);
        $mongoClient = $this->get('mongo');
        $mongoClient->mydb->notes->deleteOne(
            [
                '_id' => new ObjectID($id),
            ]
        );
        $routeParser = $app->getRouteCollector()->getRouteParser();
        return $response->withHeader('Location', $routeParser->urlFor('index', [], ['status' => 'deleted']))->withStatus(302);
    }
)->setName('delete');

// POST request handler for /hook webhook URL
$app->post(
    '/hook',
    function (Request $request, Response $response) {
        try {
            // get MongoDB service
            $mongoClient = $this->get('mongo');

            // decode JSON request body
            // obtain identifiers and status
            $json        = json_decode($request->getBody());
            $jid         = $json->job->id;
            $id          = $json->job->metadata;

            // if job successful
            if ($json->job->status === 'transcribed') {

                // update status in database
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => ['status' => 'JOB_TRANSCRIPTION_SUCCESS'],
                    ]
                );

                // get transcript from API
                $revClient   = $this->get('guzzle');
                $revResponse = $revClient->request(
                    'GET',
                    "jobs/$jid/transcript",
                    [
                        'headers' => ['Accept' => 'text/plain'],
                    ]
                )->getBody()->getContents();
                $transcript  = explode('    ', $revResponse)[2];

                // save transcript to database
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => ['data' => $transcript],
                    ]
                );
            // if job unsuccesful
            } else {

                // update status in database
                // save problem detail error message
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => [
                            'status' => 'JOB_TRANSCRIPTION_FAILURE',
                            'error'  => $json->job->failure_detail,
                        ],
                    ]
                );
            }
        } catch (\GuzzleHttp\Exception\RequestException $e) {
            $mongoClient->mydb->notes->updateOne(
                [
                  '_id' => new ObjectID($id),
                ],
                [
                  '$set' => [
                      'status' => 'JOB_TRANSCRIPTION_FAILURE',
                      'error'  => $e->getMessage(),
                  ],
                ]
            );
        }
        return $response->withStatus(200);
    }
);

$app->run();

Step 5: Test the example application

Test the example application by browsing to http://<DOCKER_HOST>. You should see the page below.

Click the "Add" button in the top right corner. You will be redirected to a new page and the browser will prompt for access to the system microphone. Grant this permission, then click the "Start recording" button. Speak and click "Stop recording" once done. Your audio will be uploaded and you should be redirected back to the index page, where you should see your voice note listed with status "In progress".

When the transcript is ready, Rev AI will notify the webhook URL. If you are using a public URL, you will be able to see this activity in the Web server logs. Alternatively, if you are using ngrok, you will be able to see this activity in the ngrok dashboard, as shown below:

When you see the incoming webhook request in the Web server logs or ngrok monitor, or after approximately 1 minute if you do not have access to monitoring, click the "Refresh" button. The list of voice notes should now reflect the updated status, together with the transcript, as shown below:

In case the transcript could not be generated due to an error, this too should be visible in the list:

Enter a search term in the search box and click the "Go" button. The list of voice notes should now be filtered to only display those containing your search term, as shown below:

Click the "Delete" button next to a voice note. The note will be deleted from the database and will vanish from the list of available notes.

Next steps

In this concluding segment, you learnt how to retrieve the final transcript from Rev AI using a webhook and display it in the Web application. You also improved the Web application with basic search and deletion features.

With this, the example speech-to-text Web application is complete. Audio is received and recorded through the browser and transcripts are generated, returned and integrated into the application with Rev AI and PHP.

Learn more about developing speech-to-text applications with Rev AI and PHP by visiting the following links:

Documentation: Asynchronous Speech-To-Text API job submission, transcript retrieval and job deletion
Code samples: Asynchronous Speech-To-Text API
Tutorial: Get Started with Rev AI API Webhooks
Tutorial: Use Webhooks to Trigger Job Email Notifications with Node.js, SendGrid and Express
Tutorial: Save Transcripts to MongoDB with a Node.js Webhook
Tutorial: Delete User Files from Rev AI
Tutorial: Asynchronous Speech-To-Text API best practices
Documentation: Slim framework
Documentation: Guzzle PHP HTTP client
Documentation: MongoDB PHP driver

Build a Speech-to-Text Web Application with Rev AI and PHP (Part 1)

Vikram Vaswani — Fri, 26 Aug 2022 13:56:57 +0000

By Vikram Vaswani, Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/build-speech-to-text-web-application-php-1/ on Aug 17, 2022.

Introduction

Rev AI's automatic speech recognition (ASR) APIs enable developers to integrate fast and accurate speech-to-text capabilities into their applications. These APIs can be used to transcribe both pre-recorded and live audio, and include features like automatic punctuation, custom vocabularies, speaker diarization.

This tutorial introduces you to Rev AI's Asynchronous Speech-to-Text API and walks you step-by-step through the process of integrating it with a Web application. It explains how to record audio through a Web application, submit this audio to Rev AI for transcription, and receive and save the transcript to the application database. Through this process, you will learn how to create a Rev AI API client, send requests to the Rev AI API, and use webhooks to receive and process API responses.

Application overview

The example application in this tutorial is conceived as a tool for people who are constantly on the move, such as medical professionals, journalists or salespeople. It provides a way for these users to record brief voice notes as reminders for themselves or others - for example, patient notes, interview ideas, to-do items and so on. It then transcribes these voice notes and makes the resulting text content viewable and searchable through a Web browser.

Internally, each time a new voice note is recorded, the application transmits the audio to the Rev AI Asynchronous Speech-to-Text API for transcription and saves the resulting text transcript to a MongoDB database. The application is implemented using PHP, with the Guzzle PHP client handling application-API communication on the server and Bootstrap and RecordRTC taking care of the client-side user interface and audio recording respectively.

NOTE: The complete source code for the example application is available on GitHub, so you can download and try it immediately.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have Docker installed. If not, download and install Docker for your operating system.
You have Docker Compose installed. If not, install Docker Compose for your operating system.
You will deploy the application at a public URL. If not, or if you prefer to develop and test locally, download and install ngrok and obtain an ngrok authentication token. You will need this to generate a temporary public URL for the webhook.

Step 1: Create the development environment

Within your project directory, create the following Dockerfile and save it as Dockerfile:

FROM php:8.1.8-apache
RUN set -eux; \
  apt-get update; \
  apt-get install -y libcurl4-openssl-dev pkg-config libssl-dev zlib1g-dev zip git; \
  pecl install mongodb; \
  docker-php-ext-enable mongodb;
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
WORKDIR /var/www
RUN set -eux; \
  a2enmod rewrite; \
  sed -i 's!/var/www/html!/var/www/public!g' /etc/apache2/sites-available/000-default.conf
EXPOSE 80

This Dockerfile inherits from the official PHP Docker image and customizes it to add the PHP MongoDB extension and the Composer dependency manager. It also activates the Apache mod_rewrite module and sets the Apache Web server document root to /var/www/public.

Next, create the following Docker Compose file and save it in the project directory as docker-compose.yml:

version: '3'
services:
    app:
        image: myapp:latest
        container_name: myapp
        ports:
            - 80:80
        volumes:
            - ./:/var/www/
        working_dir: /var/www/
        depends_on:
            - db
        build:
            context: .
            dockerfile: Dockerfile
        command:
            - /bin/bash
            - -c
            - |
              composer install
              apache2-foreground
    db:
        image: mongo:latest
        container_name: mydb
        restart: always
        environment:
          MONGO_INITDB_ROOT_USERNAME: myuser
          MONGO_INITDB_ROOT_PASSWORD: mypassword
        volumes:
            - data:/data/db/
        ports:
            - 27017:27017
volumes:
    data: {}

This Docker Compose file creates two containers: myapp for the application service (PHP/Apache) and mydb for the database service (MongoDB). It mounts the current directory as a volume in the application container at the /var/www mount point and sets root user credentials for the MongoDB service. It also overrides the default startup command of the official PHP Docker image to run composer install before starting Apache, to check for required packages and install them (if required) when the myapp container starts.

Start your development environment by executing the command below:

docker-compose up -d

Confirm that both services are running:

docker ps

You should see something like this:

CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                                           NAMES
1e360eaed7e0   myapp:latest   "docker-php-entrypoi…"   12 minutes ago   Up 12 minutes   0.0.0.0:80->80/tcp, :::80->80/tcp               myapp
3d9f343639ab   mongo:latest   "docker-entrypoint.s…"   12 minutes ago   Up 12 minutes   0.0.0.0:27017->27017/tcp, :::27017->27017/tcp   mydb

Step 2: Install required packages

This application will use the following PHP packages:

Slim: a PHP micro-framework for small Web applications
Twig-View: a template engine for Slim based on Twig
PHP-DI: a PHP dependency injection container
Slim PSR7: a strict PSR-7 implementation used by Slim
Guzzle: a PHP HTTP client
MongoDB PHP driver: a PHP API for working with MongoDB databases

Install these packages with the following command:

docker exec -it myapp composer require \
  slim/slim:4.* \
  slim/twig-view \
  php-di/php-di \
  slim/psr7 \
  guzzlehttp/guzzle:7.* \
  mongodb/mongodb \
  --with-all-dependencies

Step 3: Create and test the application skeleton

Create and test a minimal application skeleton as described below.

Create the following directories in the project:

- `public/`: for public assets
- `config/`: for application configuration
- `views/`: for page templates

```bash
mkdir public config views
```

Create the following file to store application configuration. Save it as config/settings.php and replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI access token.
```
<?php
return [
    'rev' => [
        'token' => '<REVAI_ACCESS_TOKEN>',
    ],
];
```

Prepare a simple Bootstrap base template. Save it as views/layout.twig.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">
  </head>
  <body>
    <nav class="navbar navbar-light bg-light border-bottom">
      <div class="container-fluid">
        <div class="navbar-nav">
          <a class="btn btn-primary" href="{{ url_for('index') }}" role="button">Home</a>
        </div>
      </div>
    </nav>
    <div id="content">
      {% block content %}
      {% endblock %}
    </div>
  </body>
</html>

Create a temporary index page template inheriting from the base template. Save it as views/index.twig.

{% extends "layout.twig" %}

{% block content %}
  <header class="d-flex justify-content-center py-3">
  <h1>PAGE UNDER CONSTRUCTION</h1>
  </header>
{% endblock %}

Configure URL rewriting rules for Apache and PHP file upload limits by creating the file public/.htaccess with the following content:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]
php_value upload_max_filesize 256M
php_value post_max_size 256M

Create the application front controller with the following PHP code. Save it as public/index.php.

<?php
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
use Slim\Views\Twig;
use Slim\Views\TwigMiddleware;
use Slim\Routing\RouteContext;
use DI\ContainerBuilder;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7;
use MongoDB\BSON\ObjectID;

// load dependencies
require __DIR__ . '/../vendor/autoload.php';

// create DI container
$containerBuilder = new ContainerBuilder();

// define services
$containerBuilder->addDefinitions(
    [
        'settings' => function () {
            return include __DIR__ . '/../config/settings.php';
        },
        'view'     => function () {
            return Twig::create(__DIR__ . '/../views');
        },
    ]
);

$container = $containerBuilder->build();

AppFactory::setContainer($container);

// create application with DI container
$app = AppFactory::create();

// add Twig middleware
$app->add(TwigMiddleware::createFromContainer($app));

// add error handling middleware
$app->addErrorMiddleware(true, true, true);

// GET request handler for index page
$app->get(
    '/[index[/]]',
    function (Request $request, Response $response, $args) {
        return $this->get('view')->render(
            $response,
            'index.twig',
            []
        );
    }
)->setName('index');

$app->run();

This front controller script sets up a minimal Slim application.

It begins by loading all the required classes using the Composer auto-loader.
It creates a PHP Dependency Injection (DI) container with entries for two services: settings for the application configuration and view for the Twig template engine.
It creates a new Slim application $app and associates it with the DI container.
It adds Twig-View middleware and error handling middleware to the application.
It defines a route handler named index for GET / and GET /index requests. This handler returns the temporatry views/index.twig template created previously.
It runs the application with $app->run().

Test this skeleton application by browsing to http://<DOCKER_HOST> and confirming that you see the following output:

Step 4: Capture and upload audio in the client

With the basic application skeleton defined, it's now time to move on to capturing audio. For a Web application, this is done in the client using WebRTC. A number of JavaScript libraries are available to simplify this integration; this tutorial uses the MIT-licensed RecordRTC library, which comes with extensive documentation and can be delivered to the client via CDN.

Begin by creating a page template with a start/stop recording button, as below. Save this as views/add.twig.

{% extends "layout.twig" %}

{% block content %}
  <header class="d-flex justify-content-center py-3">
    <h1>Add Note</h1>
  </header>

  <div class="d-flex justify-content-center btn-group-lg mb-5">
    <button type="button" class="btn btn-success btn-control">Start recording</button>
  </div>
  <h4 class="justify-content-center timer" style="text-align:center"></h4>

  <script src="https://cdnjs.cloudflare.com/ajax/libs/RecordRTC/5.5.6/RecordRTC.js"></script>

  <script>
  const controlButton = document.querySelector('.btn-control');
  const timer = document.querySelector('.timer');

  navigator.mediaDevices.getUserMedia({
    video: false,
    audio: true
  }).then(async function(stream) {

    const recorder = RecordRTC(stream, {
      type: 'audio',
      mimeType: 'audio/wav',
      recorderType: StereoAudioRecorder
    });

    controlButton.onclick = function() {
      if (controlButton.textContent === 'Start recording') {
        startRecording();
      } else {
        stopAndProcessRecording();
      }
    }

    startRecording = function() {
      controlButton.textContent = 'Stop recording';
      controlButton.classList.toggle('btn-danger');
      recorder.startRecording();
    }

    stopAndProcessRecording = function() {
      controlButton.disabled = true;
      recorder.stopRecording(function() {
        const blob = recorder.getBlob();
        const formData = new FormData();
        formData.append('file', blob);
        fetch('', {
          method: 'POST',
          body: formData
        })
        .then(response => {
          if (response.ok === false) {
            window.location.href = '{{ url_for('index', {}, {'status':'error'}) }}';
          } else {
            window.location.href = '{{ url_for('index', {}, {'status':'submitted'}) }}';
          }
        })
      });
    }
  }).catch(function(error) {
    console.error(error);
  });

  </script>
{% endblock %}

On page load, the script uses the getUserMedia() method of the Media Streams API to prompt the user to allow audio recording within the browser. If permission is granted, it creates a RecordRTC audio recorder object and configures it for a WAV audio stream.

The page also defines an HTML button element, which allows the user to control audio recording. When the user clicks this control button, the button's onclick event handler takes care of toggling the recorder state using two functions: startRecording() and stopAndProcessRecording().

The startRecording() function merely changes the button label and color and calls the recorder's startRecording() function.
The stopAndProcessRecording() function is more complex:
- When invoked, it first disables the button (to avoid re-recording) and then calls the recorder's stopRecording() method with a callback function.
- This callback function gets the recorded audio as a binary object (getBlob()) and uploads it to the server using a multipart/form-data POST HTTP request (fetch()).
- It uses the response.ok flag to check if the request was successful or not.
- Finally, it redirects the client back to the index page, passing along a success or error flag as a URL query parameter.

NOTE: RecordRTC logs all its operations to the console so if you're curious about how it works, watch your browser console while interacting with the above page.

Step 5: Transfer audio from the server to Rev AI

The application front controller must now be updated to accept the file uploaded in Step 4 and, in turn, trigger a transcription job request to the Rev AI Asynchronous Speech-to-Text API endpoint at https://api.rev.ai/speechtotext/v1/jobs. This request also be a multipart/form-data request containing the binary file data and job options; it must also include an Authorization header containing the Rev AI access token.

Here is an example of sending an audio file to the API for transcription:

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: multipart/form-data" \
     -F "media=@/<FILEPATH>" \
     -F "options={\"filter_profanity\":\"true\"}"

A number of options can be submitted with the job request to control the transcription process. Once the job is submitted to the Rev AI API, the API will return a unique job identifier.

Here is an example response from the API:

{
  "id":"AxYUC5GSuXZD",
  "created_on":"2022-04-25T10:41:27.535Z",
  "name":"FTC_Sample_1.mp3",
  "filter_profanity":true,
  "status":"in_progress",
  "type":"async",
  "language":"en"
}

NOTE: Files uploaded to the Asynchronous Speech-to-Text API using multipart/form-data must be less than 2 GB in size. Media files longer than 17 hours are not supported for English transcription. Read more about API limits.

Start implementing this functionality as below:

A. Update the config/settings.php file with an additional configuration key for the MongoDB database credentials. If you are using the docker-compose.yml file from Step 1, replace the <MONGODB_URI> placeholder with the credentials string mongodb://myuser:mypassword@db.

<?php
    return [
        'rev' => [
            'token' => '<REVAI_ACCESS_TOKEN>',
        ],
        'mongo' => [
            'uri' => '<MONGODB_URI>'
        ]
    ];

B. Update the front controller at public\index.php with the following changes:

Modify the DI container and initialize Guzzle and MongoDB clients, which will be used to communicate with the Rev AI API and the application database respectively:

  <?php
  // ...

  // define services
  $containerBuilder->addDefinitions(
      [
          'settings' => function () {
              return include __DIR__ . '/../config/settings.php';
          },
          'view'     => function () {
              return Twig::create(__DIR__ . '/../views');
          },
          'mongo'    => function ($c) {
              return new MongoDB\Client($c->get('settings')['mongo']['uri']);
          },
          'guzzle'   => function ($c) {
              $token = $c->get('settings')['rev']['token'];
              return new Client(
                  [
                      'base_uri' => 'https://api.rev.ai/speechtotext/v1/jobs',
                      'headers'  => ['Authorization' => "Bearer $token"],
                  ]
              );
          },
      ]
  );

  // ...

Create a GET route handler for a new /add URL endpoint, which returns the recording interface in the add.twig page template.

  <?php
  // ...

  // GET request handler for /add page
  $app->get(
    '/add',
    function (Request $request, Response $response, $args) {
        return $this->get('view')->render(
            $response,
            'add.twig',
            []
        );
    }
  )->setName('add');

  // ...

Create a POST route handler for the /add URL endpoint, which accepts and processes the uploaded audio file as described earlier.

  <?php
  // ...

  // POST request handler for /add page
  $app->post(
    '/add',
    function (Request $request, Response $response) {
        // get MongoDB service
        // insert a record in the database for the audio upload
        // get MongoDB document ID
        $mongoClient = $this->get('mongo');
        try {
            $insertResult = $mongoClient->mydb->notes->insertOne(
                [
                    'status' => 'JOB_RECORDED',
                    'ts'     => time(),
                    'jid'    => false,
                    'error'  => false,
                    'data'   => false,
                ]
            );
            $id           = (string) $insertResult->getInsertedId();

            // get uploaded file
            // if no upload errors, change status in database record
            $uploadedFiles = $request->getUploadedFiles();
            $uploadedFile = $uploadedFiles['file'];

            if ($uploadedFile->getError() === UPLOAD_ERR_OK) {
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => ['status' => 'JOB_UPLOADED'],
                    ]
                );

                // get Rev AI API client
                // submit audio to API as POST request
                $revClient   = $this->get('guzzle');
                $revResponse = $revClient->request(
                    'POST',
                    'jobs',
                    [
                        'multipart' => [
                            [
                                'name'     => 'media',
                                'contents' => fopen($uploadedFile->getFilePath(), 'r'),
                            ],
                            [
                                'name'     => 'options',
                                'contents' => json_encode(
                                    [
                                        'metadata'         => $id,
                                        'skip_diarization' => 'true',
                                    ]
                                ),
                            ],
                        ],
                    ]
                )->getBody()->getContents();

                // get API response
                // if no API error, update status in database record
                // send 200 response code to client
                $json        = json_decode($revResponse);
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => [
                            'status' => 'JOB_TRANSCRIPTION_IN_PROGRESS',
                            'jid'    => $json->id,
                        ],
                    ]
                );
                $response->getBody()->write(json_encode(['success' => true]));
                return $response->withHeader('Content-Type', 'application/json')->withStatus(200);
            }
        } catch (\GuzzleHttp\Exception\RequestException $e) {
            // in case of API error
            // update status in database record
            // send error code to client with error message as payload
            $mongoClient->mydb->notes->updateOne(
                [
                    '_id' => new ObjectID($id),
                ],
                [
                    '$set' => [
                        'status' => 'JOB_TRANSCRIPTION_FAILURE',
                        'error'  => $e->getMessage(),
                    ],
                ]
            );
            $response->getBody()->write(json_encode(['success' => false]));
            return $response->withHeader('Content-Type', 'application/json')->withStatus($e->getResponse()->getStatusCode());
        }
    }
  );

  // ...

This route handler contains a lot of code, so let's step through it:

When this endpoint is invoked with a HTTP POST request containing a multipart/form-data file upload, the handler first inserts a new document in the MongoDB database with the MongoDB client's insertOne() method. This document is empty save for the timestamp and a status field, which at this point is set to JOB_RECORDED. The handler also stores the unique document identifier returned by the MongoDB client's getInsertedId() method.
The handler gets the uploaded file via the request object's getUploadedFiles() method and check for errors via the getError() method. If the file was uploaded successfully, the document status is updated to JOB_UPLOADED using the MongoDB client's updateOne() method.
The handler uses the Guzzle Rev AI API client to prepare and send a HTTP POST request to https://api.rev.ai/speechtotext/v1/jobs. As described earlier, this is a multipart/form-data request containing the uploaded audio file and an options object containing two keys: a metadata key containing the MongoDB document identifier for later cross-referencing, and a skip_diarization flag to skip speaker diarization.
If the API request is successful, the handler decodes the JSON response body, extracts the Rev AI job identifier and adds it to the database record. It also updates the document status to JOB_TRANSCRIPTION_IN_PROGRESS. It returns a JSON document indicating success to the client with a 200 response code.
If the API request fails for any reason - for example, due to an invalid access token or a problem with the audio file - the Guzzle client will receive an error code from the API and throw an exception. The exception handler catches this exception and updates the document status to JOB_TRANSCRIPTION_FAILURE. It returns a JSON document indicating failure to the client with the Rev AI server error code. NOTE: Learn more about submitting an asynchronous transcription job and obtaining a transcript.

Update the GET route handler for the /index endpoint to take account of the new status parameter passed along in the URL by the client-side stopAndProcessRecording() function in Step 4. This parameter is transferred to the index page template as a Twig template variable.

  <?php
  // ...

  // GET request handler for index page
  $app->get(
      '/[index[/]]',
      function (Request $request, Response $response, $args) {
          $params = $request->getQueryParams();
          return $this->get('view')->render(
              $response,
              'index.twig',
              [
                  'status' => !empty($params['status']) ? $params['status'] : null,
              ]
          );
      }
  )->setName('index');

  // ...

For reference, here is the complete front controller script incorporating all the changes discussed above. Replace the public\index.php file with this version.

  <?php
  use Psr\Http\Message\ResponseInterface as Response;
  use Psr\Http\Message\ServerRequestInterface as Request;
  use Slim\Factory\AppFactory;
  use Slim\Views\Twig;
  use Slim\Views\TwigMiddleware;
  use Slim\Routing\RouteContext;
  use DI\ContainerBuilder;
  use GuzzleHttp\Client;
  use GuzzleHttp\Psr7;
  use MongoDB\BSON\ObjectID;

  // load dependencies
  require __DIR__ . '/../vendor/autoload.php';

  // create DI container
  $containerBuilder = new ContainerBuilder();

  // define services
  $containerBuilder->addDefinitions(
      [
          'settings' => function () {
              return include __DIR__ . '/../config/settings.php';
          },
          'view'     => function () {
              return Twig::create(__DIR__ . '/../views');
          },
          'mongo'    => function ($c) {
              return new MongoDB\Client($c->get('settings')['mongo']['uri']);
          },
          'guzzle'   => function ($c) {
              $token = $c->get('settings')['rev']['token'];
              return new Client(
                  [
                      'base_uri' => 'https://api.rev.ai/speechtotext/v1/jobs',
                      'headers'  => ['Authorization' => "Bearer $token"],
                  ]
              );
          },
      ]
  );

  $container = $containerBuilder->build();

  AppFactory::setContainer($container);

  // create application with DI container
  $app = AppFactory::create();

  // add Twig middleware
  $app->add(TwigMiddleware::createFromContainer($app));

  // add error handling middleware
  $app->addErrorMiddleware(true, true, true);

  // GET request handler for index page
  $app->get(
      '/[index[/]]',
      function (Request $request, Response $response, $args) {
          $params = $request->getQueryParams();
          return $this->get('view')->render(
              $response,
              'index.twig',
              [
                  'status' => !empty($params['status']) ? $params['status'] : null,
              ]
          );
      }
  )->setName('index');

  // GET request handler for /add page
  $app->get(
    '/add',
    function (Request $request, Response $response, $args) {
        return $this->get('view')->render(
            $response,
            'add.twig',
            []
        );
    }
  )->setName('add');

  // POST request handler for /add page
  $app->post(
    '/add',
    function (Request $request, Response $response) {
        // get MongoDB service
        // insert a record in the database for the audio upload
        // get MongoDB document ID
        $mongoClient = $this->get('mongo');
        try {
            $insertResult = $mongoClient->mydb->notes->insertOne(
                [
                    'status' => 'JOB_RECORDED',
                    'ts'     => time(),
                    'jid'    => false,
                    'error'  => false,
                    'data'   => false,
                ]
            );
            $id           = (string) $insertResult->getInsertedId();

            // get uploaded file
            // if no upload errors, change status in database record
            $uploadedFiles = $request->getUploadedFiles();
            $uploadedFile = $uploadedFiles['file'];

            if ($uploadedFile->getError() === UPLOAD_ERR_OK) {
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => ['status' => 'JOB_UPLOADED'],
                    ]
                );

                // get Rev AI API client
                // submit audio to API as POST request
                $revClient   = $this->get('guzzle');
                $revResponse = $revClient->request(
                    'POST',
                    'jobs',
                    [
                        'multipart' => [
                            [
                                'name'     => 'media',
                                'contents' => fopen($uploadedFile->getFilePath(), 'r'),
                            ],
                            [
                                'name'     => 'options',
                                'contents' => json_encode(
                                    [
                                        'metadata'         => $id,
                                        'skip_diarization' => 'true',
                                    ]
                                ),
                            ],
                        ],
                    ]
                )->getBody()->getContents();

                // get API response
                // if no API error, update status in database record
                // send 200 response code to client
                $json        = json_decode($revResponse);
                $mongoClient->mydb->notes->updateOne(
                    [
                        '_id' => new ObjectID($id),
                    ],
                    [
                        '$set' => [
                            'status' => 'JOB_TRANSCRIPTION_IN_PROGRESS',
                            'jid'    => $json->id,
                        ],
                    ]
                );
                $response->getBody()->write(json_encode(['success' => true]));
                return $response->withHeader('Content-Type', 'application/json')->withStatus(200);
            }
        } catch (\GuzzleHttp\Exception\RequestException $e) {
            // in case of API error
            // update status in database record
            // send error code to client with error message as payload
            $mongoClient->mydb->notes->updateOne(
                [
                    '_id' => new ObjectID($id),
                ],
                [
                    '$set' => [
                        'status' => 'JOB_TRANSCRIPTION_FAILURE',
                        'error'  => $e->getMessage(),
                    ],
                ]
            );
            $response->getBody()->write(json_encode(['success' => false]));
            return $response->withHeader('Content-Type', 'application/json')->withStatus($e->getResponse()->getStatusCode());
        }
    }
  );

  $app->run();

C. Update the views/index.twig page template to use the status Twig template variable and display a success or failure message to the user.

{% extends "layout.twig" %}

    {% block content %}
      <header class="d-flex justify-content-center py-3">
      <h1>My Notes</h1>
      </header>

      {% if status == 'submitted' %}
      <div class="alert alert-success text-center" role="alert">Audio sent for transcription.</div>
      {% endif %}

      {% if status == 'error' %}
      <div class="alert alert-danger text-center" role="alert">Audio transcription failed.</div>
      {% endif %}
{% endblock %}

D. Finally, update the base template public\layout.twig to include an additional button in the top right corner for the new "Add Note" page:

<!doctype html>
<html lang="en">
      <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">
      </head>
      <body>
        <nav class="navbar navbar-light bg-light border-bottom">
          <div class="container-fluid">
            <div class="navbar-nav">
              <a class="btn btn-primary" href="{{ url_for('index') }}" role="button">Home</a>
            </div>
            <div class="navbar-nav justify-content-end">
              <a class="btn btn-primary" href="{{ url_for('add') }}" role="button">Add</a>
            </div>
          </div>
        </nav>
        <div id="content">
          {% block content %}
          {% endblock %}
        </div>
      </body>
</html>

Step 6: Test the example application

Test the example application by browsing to http://<DOCKER_HOST> and clicking the new "Add" button in the top right corner. You should see the page below.

The browser will prompt for access to the system microphone. Grant this permission, then click the "Start recording" button. Speak and click "Stop recording" once done. Your audio will be uploaded and you should be redirected back to the index page.

Query the MongoDB database to check the status of your recording as shown below. Replace the MONGODB_URI placeholder with the same credentials used in the previous step. You will see a new MongoDB document with a Rev AI job identifier.

docker exec -it mydb mongosh <MONGODB_URI>
admin> use mydb
switched to db mydb
mydb> db.notes.find()
[
  {
    _id: ObjectId("62667cae5fac4d5871017cb2"),
    status: 'JOB_TRANSCRIPTION_IN_PROGRESS',
    ts: 1650883758,
    jid: 'JDmCeVLfjlFO',
    error: false,
    data: false
  }
]

Check your Rev AI account dashboard at https://www.rev.ai/jobs/speech-to-text. You will be able to see the status of the job and also download the final transcript.

Next steps

With this, the first part of the example speech-to-text Web application is complete, with audio being received and recorded through the browser and submitted to Rev AI for transcription. In the second part of this article, you will learn how to retrieve the final transcript from Rev AI using the API and display it in the Web application. You will also learn how to delete and search transcripts within the Web application interface

Learn more about developing speech-to-text applications with Rev AI and PHP by visiting the following links:

Documentation: Asynchronous Speech-To-Text API job submission
Code samples: Asynchronous Speech-To-Text API
Tutorial: Get Started with Speech Recognition in PHP
Tutorial: Asynchronous Speech-To-Text API best practices
Documentation: Slim framework
Documentation: Guzzle PHP HTTP client
Documentation: MongoDB PHP driver

Save Transcripts to MongoDB with a Node.js Webhook

Vikram Vaswani — Mon, 25 Jul 2022 11:42:18 +0000

By Vikram Vaswani, Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/save-transcripts-mongodb-webhooks/ on Jul 12, 2022.

Introduction

Webhooks provide a simple and efficient way to handle events that occur asynchronously outside an application's scope. They are typically set up as URL endpoints that are invoked by upstream applications on specific events. They accept incoming HTTP requests and in turn trigger application-specific processes, such as generating a notification or updating a status record.

Rev AI's Asynchronous Speech-to-Text API uses webhooks to notify applications when a transcription job is complete. On receipt of this notification, the application usually needs to retrieve the transcript and "does something" with it. This "something" could involve saving the transcript to a database, providing the user with the option to edit and correct it, or processing it in a different way.

This tutorial demonstrates how to implement a webhook in a Node.js application for one such use case. It gives you the information (and code) you need to create a webhook that, on job completion, is able to request a complete transcript from Rev AI and save it to an external MongoDB database for further processing.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have a properly-configured Node.js development environment with Node.js v16.x or v17.x. If not, download and install Node.js for your operating system.
You have some familiarity with the Express framework. If not, familiarize yourself with the basics using this example application.
You have write privileges to a MongoDB database. If not, download and install MongoDB for your operating system and configure access control, or deploy MongoDB in the cloud and configure a database, user and role with write privileges.
Your webhook will be available at a public URL. If not, or if you prefer to develop and test locally, download and install ngrok to generate a temporary public URL for your webhook.
You have an audio file to transcribe. If not, use this example audio file from Rev AI.

Step 1: Install required packages

This tutorial will use:

The Rev AI Node SDK, to submit transcription requests to the Rev AI Asynchronous Speech-to-Text API;
The MongoDB Node.js Driver, to save data to MongoDB;
The Express Web framework and body-parser middleware, to receive and parse webhook requests.

Begin by installing the required packages:

npm i revai-node-sdk mongodb express body-parser

Step 2: Create the webhook handler

The webhook URL is specified as part of the job parameters submitted to the Rev AI API. On job completion, the Rev AI API will send an HTTP POST request containing JSON-encoded details of the completed job to the webhook URL. Here is an example of one such POST request:

{
  job: {
    id: 'Qctu6UgJvTjZ',
    created_on: '2022-04-08T15:01:35.999Z',
    completed_on: '2022-04-08T15:02:05.403Z',
    name: 'FTC_Sample_1.mp3',
    callback_url: 'https://a177-49-36-111-113.ngrok.io/hook',
    media_url: 'https://www.rev.ai/FTC_Sample_1.mp3',
    status: 'transcribed',
    duration_seconds: 107,
    type: 'async',
    language: 'en'
  }
}

The following example demonstrates how to implement a webhook handler that receives and parses the HTTP POST message from the Rev AI API and then makes a subsequent request to the API to retrieve the complete transcript. The handler then saves the received data to a MongoDB database collection as a JSON document.

To use this example, you must replace the <MONGODB_CONNECTION_URI> with the connection URI to your MongoDB database and the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI account's access token.

const { RevAiApiClient } = require('revai-node-sdk');
const { MongoClient } = require('mongodb');
const bodyParser = require('body-parser');
const express = require('express');

// MongoDB connection string
const mongodbUri = '<MONGODB_CONNECTION_URI>';

// Rev AI access token
const revAiToken = '<REVAI_ACCESS_TOKEN>';

// create Express application
const app = express();
app.use(bodyParser.json());

// create Mongo client
const mongo = new MongoClient(mongodbUri);
mongo.connect();
const db = mongo.db('mydb');
const transcripts = db.collection('transcripts')

// create Rev AI API client
const revAiClient = new RevAiApiClient(revAiToken);

// handle requests to webhook endpoint
app.post('/hook', async req => {
  const job = req.body.job;
  console.log(`Received status for job id ${job.id}: ${job.status}`);

  if (job.status === 'transcribed') {
    // request transcript
    const transcript = await revAiClient.getTranscriptObject(job.id);
    console.log(`Received transcript for job id ${job.id}`);

    // create MongoDB document
    const doc = {
      job_id: job.id,
      created_on: job.created_on,
      language: job.language,
      status: job.status,
      transcript
    }

    // save document to MongoDB
    try {
      const result = await collection.insertOne(doc);
      console.log(`Saved transcript with document id: ${result.insertedId}`);
    } catch (e) {
      console.error(e);
    }
  }
});

//  start application on port 3000
app.listen(3000, () => {
  console.log('Webhook listening');
})

Save this code listing as index.js and take a closer look at it:

This code listing begins by importing the required packages and credentials and creating both a MongoDB client and a Rev AI API client.
It attempts to connect to the MongoDB database service using the MongoDB client's connect() method and selects a database and collection for use.
It starts an Express application on port 3000 and waits for incoming POST requests to the /hook URL route.
When the application receives a POST request at /hook, it parses the incoming JSON message body and checks the job id and status.
If the status is transcribed, it uses the API client's getTranscriptObject() method to retrieve the complete transcript as a JSON document.
It prepares a MongoDB document to hold the transcript. This document also includes other parameters of the job, such as the date and time, language and status.
It then uses the insertOne() method to insert the prepared document into the collection, and prints the unique MongoDB document identifier to the console.
Errors, if any, in the MongoDB connection and data insertion process are sent to the console.

Step 3: Test the webhook

To see the webhook in action, first ensure that you have replaced the placeholders as described in the previous step and then start the application using the command below.

node index.js

Next, submit an audio file for transcription to Rev AI and include the callback_url parameter in your request. This parameter specifies the webhook URL that the Rev AI API should invoke on job completion.

Here is an example of submitting an audio file with a webhook using curl.

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"media_url":"<URL>","callback_url":"http://<WEBHOOK-HOST>/hook"}'

If you prefer to submit the audio file using the Rev AI Node SDK, use this script instead:

const { RevAiApiClient } = require('revai-node-sdk');

const revAiToken = '<REVAI_ACCESS_TOKEN>';
const webhookUrl = 'http://<WEBHOOK-HOST>/hook';
const fileUrl = '<URL>';

// define job options
const jobOptions = {
  callback_url: webhookUrl,
};

// create Rev AI API client
const revAiClient = new RevAiApiClient(revAiToken);

// submit job
job = await revAiClient.submitJobUrl(fileUrl, jobOptions);

In both cases, replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI access token and the <URL> placeholder with the direct URL to your audio file. Additionally, replace the <WEBHOOK-HOST> placeholder as follows:

If you are developing and testing in the public cloud, your Express application will typically be available at a public domain or IP address. In this case, replace the <WEBHOOK-HOST> placeholder with the correct domain name or IP address, including the port number 3000 if required.
If you are developing and testing locally, your Express application will not be available publicly and you must therefore configure a public forwarding URL using a tool like ngrok. Obtain this URL using the command ngrok http 3000 and replace the <WEBHOOK-HOST> placeholder with the temporary forwarding URL generated by ngrok.

Once the job is processed, the Rev AI API will send a POST request to the webhook URL. The webhook will then request the complete transcript and save it to the MongoDB database as a JSON document, as explained in the previous section.

Here is an example of the output generated by the webhook handler:

Webhook listening
Received status for job id Qctu6UgJvTjZ: transcribed
Received transcript for job id Qctu6UgJvTjZ
Saved transcript with document id: 62504e6fcc32c9387208c875

You can retrieve the transcript for review or further processing by connecting to the MongoDB database and obtaining the document using its unique identifier. An example of doing this with mongosh is shown below:

test> use mydb
mydb> db.transcripts.find( { '_id':ObjectId('62504e6fcc32c9387208c875') } )

[
  {
    _id: ObjectId("62504e6fcc32c9387208c875"),
    job_id: 'Qctu6UgJvTjZ',
    created_on: '2022-04-08T15:01:35.999Z',
    language: 'en',
    status: 'transcribed',
    transcript: {
      monologues: [
        {
          speaker: 0,
          elements: [
            {
              type: 'text',
              value: 'Hi',
              ts: 0.26,
              end_ts: 0.48,
              confidence: 0.99
            },
            { type: 'punct', value: ',' },
            {
              ...
            }
          ]
        }
      ]
    }
  }
]

If a webhook doesn't work as expected, you can test and inspect the webhook response.

Next steps

Learn more about using webhooks for asynchronous processing by visiting the following links:

Documentation: Asynchronous Speech-To-Text API job submission and webhooks
Tutorial: Get Started with Rev AI API Webhooks
Tutorial: Use Webhooks to Trigger Job Email Notifications with Node.js, SendGrid and Express
Documentation: Using ngrok
Documentation: MongoDB
Documentation: MongoDB Node.js Driver

Integrate Rev AI's Topic Extraction API with a Node.js Application

Vikram Vaswani — Tue, 12 Jul 2022 13:04:40 +0000

By Vikram Vaswani, Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/integrate-topic-extraction-api-nodejs/ on Jun 13, 2022.

Introduction

Topic extraction attempts to detect the topics or subjects of a document. It is useful in a number of different scenarios, including

Auto-generated agendas for meetings and phone calls
Automated classification or keyword indexing for digital media libraries
Automated tagging for Customer Service (CS) complaints or support tickets

Rev AI offers a Topic Extraction API that identifies important keywords and corresponding topics in transcribed speech. For application developers, it provides a fast and accurate way to retrieve and rank the core subjects in a transcribed conversation and then take further actions based on this information.

This tutorial explains how to integrate the Rev AI Topic Extraction API into your Node.js application.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have a properly-configured Node.js development environment with Node.js v16.x or v17.x. If not, download and install Node.js for your operating system.
You have a JSON transcript generated from the Asynchronous Speech-to-Text API. If not, use this example JSON transcript.

NOTE: The Topic Extraction API is under active development. Always refer to the API documentation for the most up-to-date information.

Step 1: Install Axios

The Topic Extraction API is a REST API and, as such, you will need an HTTP client to interact with it. This tutorial uses Axios, a popular Promise-based HTTP client for Node.js.

Begin by installing Axios into your application directory:

npm install axios

Within your application code, initialize Axios as below:

const axios = require('axios');
const token = '<REVAI_ACCESS_TOKEN>';

// create a client
const http = axios.create({
  baseURL: 'https://api.rev.ai/topic_extraction/v1beta/',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

Here, the Axios HTTP client is initialized with the base endpoint for the Topic Extraction API, which is https://api.rev.ai/topic_extraction/v1beta/.

Every request to the API must be in JSON format and must include an Authorization header containing your API access token. The code shown above also attaches these required headers to the client.

Step 2: Submit transcript for topic extraction

To perform topic extraction on a transcript, you must begin by submitting an HTTP POST request containing the transcript content, in either plaintext or JSON, to the API endpoint at https://api.rev.ai/topic_extraction/v1beta/jobs.

The code listings below perform this operation using the HTTP client initialized in Step 1, for both plaintext and JSON transcripts:

const submitTopicExtractionJobText = async (textData) => {
  return await http.post(`jobs`,
    JSON.stringify({
      text: textData
    }))
    .then(response => response.data)
    .catch(console.error);
};

const submitTopicExtractionJobJson = async (jsonData) => {
  return await http.post(`jobs`,
    JSON.stringify({
      json: jsonData
    }))
    .then(response => response.data)
    .catch(console.error);
};

If you were to inspect the return value of the functions shown above, here is an example of what you would see:

{
  id: 'W6DvsEjteqwV',
  created_on: '2022-04-13T09:16:07.033Z',
  status: 'in_progress',
  type: 'topic_extraction'
}

The API response contains a job identifier (id field). This job identifier will be required to check the job status and obtain the job result.

Learn more about submitting a topic extraction job in the API reference guide.

Step 3: Check job status

Topic extraction jobs usually complete within 10-20 seconds. To check the status of the job, you must submit an HTTP GET request to the API endpoint at https://api.rev.ai/topic_extraction/v1beta/jobs/<ID>, where <ID> is a placeholder for the job identifier.

The code listing below demonstrates this operation:

const getTopicExtractionJobStatus = async (jobId) => {
  return await http.get(`jobs/${jobId}`)
    .then(response => response.data)
    .catch(console.error);
};

Here is an example of the API response to the previous request after the job has completed:

{
  id: 'W6DvsEjteqwV',
  created_on: '2022-04-13T09:16:07.033Z',
  completed_on: '2022-04-13T09:16:07.17Z',
  word_count: 13,
  status: 'completed',
  type: 'topic_extraction'
}

Learn more about retrieving the status of a topic extraction job in the API reference guide.

Step 4: Retrieve topic extraction report

Once the topic extraction job's status changes to completed, you can retrieve the results by submitting an HTTP GET request to the API endpoint at https://api.rev.ai/topic_extraction/v1beta/jobs/<ID>/result, where <ID> is a placeholder for the job identifier.

The code listing below demonstrates this operation:

const getTopicExtractionJobResult = async (jobId) => {
  return await http.get(`jobs/${jobId}/result`,
    { headers: { 'Accept': 'application/vnd.rev.topic.v1.0+json' } })
    .then(response => response.data)
    .catch(console.error);
};

If the job status is completed, the return value of the above function is a JSON-encoded response containing a sentence-wise topic extraction report. If the job status is not completed, the function will return an error instead.

Here is an example of the topic extraction report returned from a completed job:

{
  "topics": [
    {
      "topic_name": "incredible team",
      "score": 0.9,
      "informants": [
        {
          "content": "We have 17 folks and, uh, I think we have an incredible team and I just want to talk about some things that we've done that I think have helped us get there.",
          "ts": 71.4,
          "end_ts": 78.39
        },
        {
          "content": "Um, it's sort of the overall thesis for this one.",
          "ts": 78.96,
          "end_ts": 81.51
        },
        {
          "content": "One thing that's worth keeping in mind is that recruiting is a lot of work.",
          "ts": 81.51,
          "end_ts": 84
        },
        {
          "content": "Some people think that you can raise money and spend a few weeks building your team and then move on to more",
          "ts": 84.21,
          "end_ts": 88.47
        }
      ]
    },
    {
      ...
    }
  ]
}

It’s also possible to filter the result set to return only topics which score above a certain value by adding a threshold query parameter to the request.

Learn more about obtaining a topic extraction report in the API reference guide.

Step 5: Create and test a simple application

Using the code samples shown previously, it's possible to create a simple application that accepts a JSON transcript and returns a list of topics detected in it, as shown below:

const main = async (jsonData) => {
  const job = await submitTopicExtractionJobJson(jsonData);
  console.log(`Job submitted with id: ${job.id}`);

  await new Promise((resolve, reject) => {
    const interval = setInterval(() => {
      getTopicExtractionJobStatus(job.id)
        .then(r => {
          console.log(`Job status: ${r.status}`);
          if (r.status !== 'in_progress') {
            clearInterval(interval);
            resolve(r);
          }
        })
        .catch(e => {
          clearInterval(interval);
          reject(e);
        });
    }, 15000);
  });

  const jobResult = await getTopicExtractionJobResult(job.id);
  console.log(jobResult);
};

// extract topics from example Rev AI JSON transcript
http.get('https://www.rev.ai/FTC_Sample_1_Transcript.json')
  .then(response => main(response.data));

This example application begins by fetching Rev AI's example JSON transcript and passing it to the main() function as input to be analyzed. The main() function submits this data to the Topic Extraction API using the submitTopicExtractionJobJson() method. It then uses setInterval() to repeatedly poll the API every 15 seconds to obtain the status of the job. Once the job status is no longer in_progress, it uses the getTopicExtractionJobResult() method to retrieve the job result and prints it to the console.

Here is an example of the output returned by the code above:

Job submitted with id: xgKIzeODYYba
Job status: completed
{
  topics: [
    { topic_name: 'quick overview', score: 0.9, informants: [Array] },
    { topic_name: 'concert tickets', score: 0.9, informants: [Array] },
    { topic_name: 'dividends', score: 0.9, informants: [Array] },
    { topic_name: 'quick background', score: 0.6, informants: [Array] }
  ]
}

NOTE: The code listing above polls the API repeatedly to check the status of the topic extraction job. This is presented only for illustrative purposes and is strongly recommended against in production scenarios. For production scenarios, use webhooks to asynchronously receive notifications once the topic extraction job completes.

Next steps

Learn more about the topics discussed in this tutorial by visiting the following links:

Documentation: Topic Extraction API reference
Documentation: Topic Extraction API webhooks
Tutorial: Get Started with Topic Extraction
Tutorial: Get Started with Rev AI Webhooks

Get Started with Speech Recognition in PHP

Vikram Vaswani — Tue, 31 May 2022 19:52:45 +0000

By Vikram Vaswani, Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/get-started-php/ on May 31, 2022.

Introduction

Rev AI offers a suite of speech-to-text APIs to help developers build automatic speech recognition (ASR) into their applications. These APIs cover a variety of use cases, including live and pre-recorded audio transcription, language identification, sentiment analysis and topic extraction.

To help developers integrate these APIs into their applications, Rev AI also offers SDKs for Node, Java and Python. However, because most of these APIs are REST APIs, it's also easy to use them with other languages...including one of my most frequently-used ones, PHP.

In this tutorial, I'll introduce you to the basics of using Rev AI's Asynchronous Speech-to-Text API using PHP and Guzzle. If you've ever wondered if you could add speech recognition to your PHP application, but didn't know where to start, this tutorial will give you all the information you need to start making requests to, and handling responses from, Rev AI's ASR APIs.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have a properly-configured PHP development environment with PHP 7.4.x or PHP 8.0.x. If not, download and install PHP for your operating system.
You have installed Composer, the PHP dependency manager. If not, download and install Composer for your operating system.
You have an audio file to transcribe. If not, use this example audio file from Rev AI.

Step 1: Install Guzzle

The Asynchronous Speech-to-Text API is a REST API and, as such, you will need an HTTP client to interact with it. This tutorial uses Guzzle 7.x, a popular PHP HTTP client.

Begin by installing Guzzle into your application directory with Composer:

composer require guzzlehttp/guzzle:^7.0

Within your application code, initialize Guzzle as below. Replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI access token:

<?php

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$token = '<REVAI_ACCESS_TOKEN>';

$client = new Client([
    'base_uri' => 'https://api.rev.ai/speechtotext/v1',
    'headers' => ['Authorization' => "Bearer $token"]
]);

Here, the Guzzle HTTP client is initialized with the base endpoint for the Asynchronous Speech-to-Text API, which is https://api.rev.ai/speechtotext/v1/.

Every request to the API must be in JSON format and must include an Authorization header containing your API access token. The code shown above also attaches this required header to the client.

Step 2: Submit a file for transcription

To generate a transcript from an audio file, you must begin by submitting an HTTP POST request to the API endpoint at https://api.rev.ai/speechtotext/v1/jobs.

The following example demonstrates how to submit a remote audio file for transcription.

To use this example, replace the <URL> placeholder with the public URL to the file you wish to transcribe and the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI account's access token.

<?php

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$token = '<REVAI_ACCESS_TOKEN>';
$fileUrl = '<URL>';

// create client
$client = new Client([
    'base_uri' => 'https://api.rev.ai/speechtotext/v1/',
    'headers' => ['Authorization' => "Bearer $token"]
]);

// send POST request and get response body
$response = $client->request(
    'POST',
    'jobs',
    ['json' => ['media_url' => $fileUrl]]
)
->getBody()
->getContents();

// decode response JSON and print
print_r(json_decode($response));

This example makes a POST request to the API, passing it the URL to the audio file to be transcribed as a JSON document. The response body is then received, parsed and decoded into a PHP object and printed to the console.

To run this example, save it as a file, such as example.php and then execute php example.php.

Here is an example of the script output, representing the API response:

stdClass Object
(
    [id] => sTfRgVlLCYkt
    [created_on] => 2022-04-06T13:35:40.6Z
    [name] => FTC_Sample_1.mp3
    [media_url] => https://www.rev.ai/FTC_Sample_1.mp3
    [status] => in_progress
    [type] => async
    [language] => en
)

The API response contains a job identifier (id field). This job identifier will be required to check the job status and obtain the job result.

It is also possible to use a local audio file and submit it to the API as multipart/form-data.

The following example demonstrates how to submit a local audio file for transcription.

To use this example, replace the <FILEPATH> placeholder with the path to the file you wish to transcribe and the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI account's access token.

<?php

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$token = '<REVAI_ACCESS_TOKEN>';
$file = '<FILEPATH>';

// create client
$client = new Client([
    'base_uri' => 'https://api.rev.ai/speechtotext/v1/',
    'headers' => ['Authorization' => "Bearer $token"]
]);

// send POST request and get response body
$response = $client->request(
    'POST',
    'jobs',
    ['multipart' => [['name' => 'media','contents' => fopen($file, 'r')]]]
)
->getBody()
->getContents();

// decode response JSON and print
print_r(json_decode($response));

Learn more about submitting an asynchronous transcription job in the API reference guide.

Step 3: Check transcription status

To check the status of the transcription job, you must submit an HTTP GET request to the API endpoint at https://api.rev.ai/speechtotext/v1/jobs/<ID>, where <ID> is a placeholder for the job identifier.

The following example demonstrates how to check the status of an asynchronous transcription job.

To use this example, replace the <ID> placeholder with the job identifier and the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI account's access token.

<?php

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$token = '<REVAI_ACCESS_TOKEN>';
$jobId = '<ID>';

// create client
$client = new Client([
  'base_uri' => 'https://api.rev.ai/speechtotext/v1/',
  'headers' => ['Authorization' => "Bearer $token"]
]);

// send GET request and get response body
$response = $client->request(
    'GET',
    "jobs/$jobId"
)
->getBody()
->getContents();

// decode response JSON and print
print_r(json_decode($response));

Here is an example of the script output after the job has completed:

stdClass Object
(
    [id] => sTfRgVlLCYkt
    [created_on] => 2022-04-06T13:35:40.6Z
    [completed_on] => 2022-04-06T13:36:16.275Z
    [name] => FTC_Sample_1.mp3
    [media_url] => https://www.rev.ai/FTC_Sample_1.mp3
    [status] => transcribed
    [duration_seconds] => 107
    [type] => async
    [language] => en
)

Learn more about retrieving the status of an asynchronous transcription job in the API reference guide.

Step 4: Retrieve the transcript

Once the job's status changes to transcribed, you can retrieve the results by submitting an HTTP GET request to the API endpoint at https://api.rev.ai/speechtotext/v1/jobs/<ID>/result, where <ID> is a placeholder for the job identifier.

The following example demonstrates how to retrieve the results of an asynchronous transcription job.

To use this example, replace the <ID> placeholder with the job identifier and the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI account's access token.

<?php

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$token = '<REVAI_ACCESS_TOKEN>';
$jobId = '<ID>';

// create client
$client = new Client([
    'base_uri' => 'https://api.rev.ai/speechtotext/v1/',
    'headers' => ['Authorization' => "Bearer $token"]
]);

// send GET request and get response body
$response = $client->request(
    'GET',
    "jobs/$jobId/transcript",
    ['headers' => ['Accept' => 'application/vnd.rev.transcript.v1.0+json']]
)
->getBody()
->getContents();

// decode response JSON and print
print_r(json_decode($response));

If the job status is transcribed, the return value of the above function is a JSON-encoded response containing a sentence-wise sentiment analysis report. If the job status is not transcribed, the function will return an error instead.

Here is an example of the transcript returned from a successful job, represented as a PHP object:

stdClass Object
(
    [monologues] => Array
        (
            [0] => stdClass Object
                (
                    [speaker] => 0
                    [elements] => Array
                        (
                            [0] => stdClass Object
                                (
                                    [type] => text
                                    [value] => Hi
                                    [ts] => 0.27
                                    [end_ts] => 0.48
                                    [confidence] => 1
                                )
                            [1] => stdClass Object
                                (
                                    [type] => punct
                                    [value] => ,
                                )
                            [2] => stdClass Object
                                (
                                    [type] => punct
                                    [value] =>
                                )
                            ...
                        )
                )
        )
)

Learn more about obtaining a transcript in the API reference guide.

Step 5: Create and test a simple application

Using the code samples shown previously, it's possible to create a custom Rev AI API client class encapsulating these functions:

<?php

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

class RevAiApiClient extends Client
{
    /**
     * @var $client GuzzleHttp client object
     *
     */
    private $client;

    /**
     * Construct API client with default base path
     * and authorization
     *
     * @param string $token Rev AI access token
     */
    public function __construct($token)
    {
        if (!isset($token)) {
            throw new Exception('Access token missing');
        }

        $this->client = new Client([
            'base_uri' => 'https://api.rev.ai/speechtotext/v1/',
            'headers' => ['Authorization' => "Bearer $token"],
        ]);
    }


    /**
     * Submit a remote audio file for transcription
     *
     * @param string $fileUrl URL to remote file
     *
     * @return stdClass Rev AI Jobs API endpoint response object
     */
    public function submitAsychronousJobRemote($fileUrl)
    {
        return json_decode(
            $this->client->request(
                'POST',
                'jobs',
                ['json' => ['media_url' => $fileUrl]]
            )->getBody()->getContents()
        );
    }

    /**
     * Submit a local audio file for transcription
     *
     * @param string $file Path to local file
     *
     * @return stdClass Rev AI Jobs API endpoint response object
     */
    public function submitAsychronousJobLocal($file)
    {
        return json_decode(
            $this->client->request(
                'POST',
                'jobs',
                ['multipart' => [['name' => 'media','contents' => fopen($file, 'r')]]]
            )->getBody()->getContents()
        );
    }

    /**
     * Get transcription job status
     *
     * @param string $id Transcription job ID
     *
     * @return stdClass Rev AI Jobs API endpoint response object
     */
    public function getAsychronousJobStatus($id)
    {
        return json_decode(
            $this->client->request(
                'GET',
                "jobs/$id"
            )->getBody()->getContents()
        );
    }

    /**
     * Get transcription job result
     *
     * @param string $id Transcription job ID
     *
     * @return stdClass Rev AI Transcript API endpoint response object
     */
    public function getAsychronousJobResult($id)
    {
        return json_decode(
            $this->client->request(
                'GET',
                "jobs/$id/transcript",
                ['headers' => ['Accept' => 'application/vnd.rev.transcript.v1.0+json']]
            )->getBody()->getContents()
        );
    }
}

Save the above client as RevAiApiClient.php.

You can now use this client in a simple application that accepts a local audio file and returns its transcript, as shown below:

<?php
require __DIR__ . '/RevAiApiClient.php';

$token = '<REVAI_ACCESS_TOKEN>';
$file = '<FILEPATH>';

// initialize the Rev AI API client
$client = new RevAiApiClient($token);

// submit a local file for transcription
$jobSubmissionResponse = $client->submitAsychronousJobLocal($file);

// get the job ID and status
$jobId = $jobSubmissionResponse->id;
$jobStatus = $jobSubmissionResponse->status;
echo "Job submitted with id: $jobId" . PHP_EOL;

// check the job status periodically
while ($jobStatus == 'in_progress') {
    $jobStatus = $client->getAsychronousJobStatus($jobId)->status;
    echo "Job status: $jobStatus" . PHP_EOL;
    sleep(30);
}

// retrieve and print the transcript
if ($jobStatus == 'transcribed') {
    print_r($client->getAsychronousJobResult($jobId));
}

This example application begins by initializing an instance of the RevAiApiClient object defined previously, passing the Rev AI access token to the object constructor. It then submits a local file for transcription using the object's submitAsychronousJobLocal() method. It then uses the getAsychronousJobStatus() method to repeatedly poll the API every 30 seconds to obtain the status of the job. Once the job status is no longer in_progress, it uses the getAsychronousJobResult() method to retrieve the transcript and prints it to the console.

Here is an example of the output generated by the example application:

Job submitted with id: RWviMy7nISeS
Job status: in_progress
Job status: transcribed
stdClass Object
(
    [monologues] => Array
        (
            [0] => stdClass Object
                (
                    [speaker] => 0
                    [elements] => Array
                        (
                            [0] => stdClass Object
                                (
                                    [type] => text
                                    [value] => 1, 2, 3
                                    [ts] => 0.03
                                    [end_ts] => 2.31
                                    [confidence] => 0.95
                                )
                            [1] => stdClass Object
                                (
                                    [type] => punct
                                    [value] => .
                                )
                        )
                )
        )
)

NOTE: The example above polls the API repeatedly to check the status of the transcription job. This is presented only for illustrative purposes and is strongly recommended against in production scenarios. For production scenarios, use webhooks to asynchronously receive notifications once the job completes.

Next steps

Learn more about the topics discussed in this tutorial by visiting the following links:

Documentation: Asynchronous Speech-To-Text API job submission
Code samples: Asynchronous Speech-To-Text API
Documentation: Asynchronous Speech-To-Text API best practices
Tutorial: Get Started with Rev AI API Webhooks

Transcribe Audio with Automatic Language Identification

Vikram Vaswani — Tue, 17 May 2022 17:42:51 +0000

By Vikram Vaswani, Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/transcribe-audio-automatic-language-identification/ on May 16, 2022.

Introduction

Rev AI's Asynchronous Speech-to-Text API is able to transcribe spoken audio even if it's not in English – simply specify the language of the audio file in your transcription job request. However, this assumes that your application is able to identify the language before requesting transcription...and this may not always be the case.

That's where Rev AI's Language Identification API comes in. This API is able to automatically identify the most probable language used in an audio file. It accepts and analyzes an input audio file and returns a list of possible languages, ranked by confidence.

A unique feature of the Language Identification API is that it performs language identification without requiring a list of possible language codes upfront. This feature eliminates the need to first acquire and validate information on language possibilities, reducing work (and code dependencies) for developers.

This tutorial explains how to integrate the Language Identification API with the Asynchronous Speech-to-Text API. It uses a webhook to create a seamless, asynchronous language identification and transcription process for use in ASR applications.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have a properly-configured Node.js development environment with Node.js v16.x or v17.x. If not, download and install Node.js for your operating system.
You have some familiarity with webhooks. If not, learn the basics of using Rev AI API webhooks and then read about using webhooks to send email notifications on job completion.
You have some familiarity with the Express framework. If not, familiarize yourself with the basics using this example application.
Your webhook will be available at a public URL. If not, or if you prefer to develop and test locally, download and install ngrok to generate a temporary public URL for your webhook.
You have an audio file to transcribe. If not, use this example audio file from Rev AI.

NOTE: The Language Identification API is under active development. Always refer to the API documentation for the most up-to-date information.

Technical approach

There are two stages in performing transcription with automatic language identification.

Stage 1: Language identification

To perform language identification on an audio file, you must submit an HTTP POST request with various parameters (including either the audio file or its URL) to the API endpoint at https://api.rev.ai/language_identification/v1/jobs. Here is an example request:

curl -X POST "https://api.rev.ai/languageid/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"media_url":"https://www.rev.ai/FTC_Sample_1.mp3","callback_url":"https://example.com/callback"}'

When a webhook URL is included with the job parameters, as in the example above, then, on job completion, the Language Identification API will send an HTTP POST request containing the job status to the specified webhook URL.

The webhook URL handler will receive and parse this status and, if successful, it will make a GET request to the API endpoint at https://api.rev.ai/language_identification/v1/jobs/<ID>/result to obtain the list of identified languages. The most probable language for the submitted audio file is specified in the top_language property of the final response. Here is an example response:

{
  "top_language": "en",
  "language_confidences": [
    {
      "language": "en",
      "confidence": 0.907
    },
    {
      "language": "nl",
      "confidence": 0.023
    }
  ]
}

Stage 2: Transcription

With the language identification complete, the webhook URL handler will then trigger a new transcription request to the Asynchronous Speech-to-Text API endpoint at https://api.rev.ai/speechtotext/v1/jobs, passing along the language identification data with the request. Here is an example request:

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"media_url":"https://www.rev.ai/FTC_Sample_1.mp3","language":"en","callback_url":"https://example.com/callback"}'

Here too, since a webhook URL is included with the job parameters, the Asynchronous Speech-to-Text API will send an HTTP POST request containing the job status to the specified webhook URL once the job is complete.

The webhook URL handler will check this status and, if it is successful, it will make a GET request to the API endpoint at https://api.rev.ai/speechtotext/v1/jobs/<ID>/transcript to obtain the final transcript. Here is an example transcript response from the API:

{
  "monologues": [
    {
      "speaker": 1,
      "elements": [
        {
          "type": "text",
          "value": "Hi",
          "ts": 0.27,
          "end_ts": 0.32,
          "confidence": 1
        },
        {
          "type": "punct",
          "value": ","
        },
        {
          "type": "punct",
          "value": " "
        },
        {
          "type": "text",
          "value": "my",
          "ts": 0.35,
          "end_ts": 0.46,
          "confidence": 1
        },
        {
          "type": "punct",
          "value": " "
        },
        {
          "type": "text",
          "value": "name's",
          "ts": 0.47,
          "end_ts": 0.59,
          "confidence": 1
        },
        {
          ...
        }
      ]
    },
    {
      ...
    }
  ]
}

NOTE: Learn more about submitting an asynchronous transcription job and obtaining a transcript.

Sequence diagram

The following diagram explains the communication between the client and the two APIs visually:

As an alternative to custom-crafting HTTP GET and POST requests to various API endpoints and evaluating the resulting responses, this tutorial uses the Rev AI Node SDK, which provides ready-made, tested and documented methods to communicate with the different Rev AI APIs.

Step 1: Install required packages

This tutorial will use:

The Rev AI Node SDK, to submit language identification and transcription requests to the Rev AI APIs;
The Express Web framework and body-parser middleware, to receive and parse webhook requests.

Begin by installing the required packages:

npm i revai-node-sdk express body-parser

Step 2: Create a webhook handler

The next step is to define a webhook handler within the application that receives job notifications from the APIs.

The following example demonstrates a webhook handler that receives both language identification and transcription job results from the respective APIs. If the results are successful, it performs the following additional processing:

For language identification jobs, it obtains the list of identified languages and the most probable language, and then initiates an asynchronous transcription request that includes this language information.
For asynchronous transcription jobs, it obtains the final transcript and prints it to the console.

To use this example, replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI account's access token.

const { RevAiApiClient } = require('revai-node-sdk');
const bodyParser = require('body-parser');
const express = require('express');
const axios = require('axios');

const token = '<REVAI_ACCESS_TOKEN>';

// create Axios client
const http = axios.create({
  baseURL: 'https://api.rev.ai/',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

// create Rev AI API client
const revAiClient = new RevAiApiClient(token);

const getLanguageIdentificationJobResult = async (jobId) => {
  return await http.get(`languageid/v1beta/jobs/${jobId}/result`,
    { headers: { 'Accept': 'application/vnd.rev.languageid.v1.0+json' } })
    .then(response => response.data)
    .catch(console.error);
};

// create Express application
const app = express();
app.use(bodyParser.json());

// define webhook handler
app.post('/hook', async req => {
  // get job, media URL, callback URL
  const job = req.body.job;
  const fileUrl = job.media_url;
  const callbackUrl = job.callback_url;
  console.log(`Received status for job id ${job.id}: ${job.status}`);

  try {
    switch (job.type) {
      // language job result handler
      case 'language_id':
        if (job.status === 'completed') {
          const languageJobResult = await getLanguageIdentificationJobResult(job.id);
          // retrieve most probable language
          // use as input to transcription request
          const languageId = languageJobResult.top_language;
          console.log(`Received result for job id ${job.id}: language '${languageId}'`);
          const transcriptJobSubmission = await revAiClient.submitJobUrl(fileUrl, {
            language: languageId,
            callback_url: callbackUrl
          });
          console.log(`Submitted for transcription with job id ${transcriptJobSubmission.id}`);
        }
        break;
      // transcription job result handler
      case 'async':
        if (job.status === 'transcribed') {
          // retrieve transcript
          const transcriptJobResult = await revAiClient.getTranscriptObject(job.id);
          console.log(`Received transcript for job id ${job.id}`);
          // do something with transcript
          // for example: print to console
          console.log(transcriptJobResult);
        }
        break;
    }
  } catch (e) {
    console.error(e);
  }
});


//  start application on port 3000
app.listen(3000, () => {
  console.log('Webhook listening');
})

Save this code listing as index.js and take a closer look at it:

This code listing begins by importing the required packages and credentials and creating a Rev AI API client RevAiApiClient for the Asynchronous Speech-to-Text API. It also creates an Axios HTTP client http for the Language Identification API.
It starts an Express application on port 3000 and waits for incoming POST requests to the /hook URL route.
When the application receives a POST request at /hook, it parses the incoming JSON message body, extracts the file and callback URLs and checks the job type.
For language identification jobs (type: language_id):
- It checks the job status and if completed, it requests the list of identified languages via the getLanguageIdentificationJobResult() function. The returned object contains a top_language property with the language code for the most probable language.
- It submits the audio file for transcription using the Rev AI API client's submitJobUrl() method. The second argument to this method is an object containing job parameters. Here, the parameters are the webhook URL (callback_url), which is set to the current webhook URL, and the language (language), which is set to the top_language value.
For asynchronous transcription jobs (type: async):
- It checks the job status and if transcribed, it uses the client's getTranscriptObject() method to retrieve the complete transcript as a JSON document. This transcript can then be processed further depending on the requirements of the application. In this illustrative example, it is simply sent to the console but for more complex scenarios, it could be saved to a database, presented to the user for review, or acted upon in a different way.
Errors, if any, in the above process are sent to the console.

Step 3: Test the webhook

To see the webhook in action, first ensure that you have replaced the placeholders as described in the previous step and then start the application using the command below.

node index.js

Next, submit an audio file for language identification to Rev AI and include the callback_url parameter in your request. This parameter specifies the webhook URL that the Rev AI API should invoke on job completion.

Here is an example of submitting an audio file with a webhook using curl.

curl -X POST "https://api.rev.ai/languageid/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"media_url":"<URL>","callback_url":"http://<WEBHOOK-HOST>/hook"}'

Replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI access token and the <URL> placeholder with the direct URL to your audio file. Additionally, replace the <WEBHOOK-HOST> placeholder as follows:

If you are developing and testing in the public cloud, your Express application will typically be available at a public domain or IP address. In this case, replace the <WEBHOOK-HOST> placeholder with the correct domain name or IP address, including the port number 3000 if required.
If you are developing and testing locally, your Express application will not be available publicly and you must therefore configure a public forwarding URL using a tool like ngrok. Obtain this URL using the command ngrok http 3000 and replace the <WEBHOOK-HOST> placeholder with the temporary forwarding URL generated by ngrok.

Once the job is processed, the Rev AI Language Identification API will send a POST request to the webhook URL. This will trigger the process described above and shortly after, the transcript will be printed to the console. The transcript can also be viewed through the Rev AI dashboard.

If the webhook doesn't work as expected, you can test and inspect the webhook data.

Next steps

Learn more about Rev AI language identification, asynchronous transcription and webhook usage by visiting the following links:

Documentation: Language Identification API overview, job submission and webhooks
Documentation: Asynchronous Speech-To-Text API overview, job submission and webhooks
Tutorial: Get Started with Rev AI Webhooks
Tutorial: Use Webhooks to Trigger Job Email Notifications with Node.js, SendGrid and Express
Documentation: Using ngrok

Recover from Connection Errors and Timeouts in Rev AI Streaming Transcription Sessions

Vikram Vaswani — Mon, 09 May 2022 18:26:54 +0000

By Kyle Bridburg, Engineering Manager and Vikram Vaswani, Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/recover-connection-streaming-api/ on May 09, 2022.

Introduction

Rev AI's Streaming Speech-to-Text API enables real-time transcription for streaming audio. It works with all major English accents and includes key features such as punctuation, capitalization, speaker diarization, custom vocabulary and profanity filtering.

The Streaming Speech-to-Text API can be used with both WebSocket and RTMP streams, with a time limit of 3 hours per stream. While this is more than sufficient for most scenarios, there are cases where live streams can run longer than 3 hours - for example, live transcription of commentary for a day-long sporting event.

With Rev AI, the recommended practice when a stream approaches the 3-hour limit is to initialize a new concurrent WebSocket connection and switch to it. This sounds simple but in practice, application developers often struggle with implementing solutions that handle connection disruption correctly (whether due to session length timeouts or other network connectivity interruptions).

This tutorial proposes some solutions for the above challenge, with a view to helping developers implement better real-time transcription solutions for long-running audio streams.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have some familiarity with Rev AI's Streaming Speech-to-Text API. If not, familiarize yourself with the basics and learn about making WebSocket requests and receiving API responses.
You have a properly-configured Node.js development environment with Node.js v16.x or v17.x. If not, download and install Node.js for your operating system.
You have installed the Rev AI Node SDK.
You have an audio file in RAW format.

Key challenges

When integrating Rev AI live transcription with long-running audio streams, developers have to be cognizant of the following issues:

Connection disruption

Rev AI's Streaming Speech-to-Text API sets a time limit per stream of 3 hours. When a stream's 3-hour limit is reached, the streaming connection will be terminated by the API. Apart from this, the streaming connection may also be disrupted due to external factors, such as network failures or bandwidth limitations.

In both these cases, the application will need to initialize a new WebSocket connection and start a new streaming session. Once the new WebSocket connection is accepted and the connected message is received, the application can begin streaming audio to it.

Data loss

When reconnecting to the API for any of the reasons described above, there is invariably a period of time when audio data is produced, but not transferred to the API for transcription. It is important for the application developer to have a strategy in place to avoid losing this audio data during the connection recovery process.

In this case, the application will need to store the audio data in a buffer until such time as the connection to the API is re-established and the data can be sent for (delayed) transcription.

Timestamp corruption

Rev AI's transcripts include timestamps for every transcribed word. Timestamps correspond to when the words are spoken within the audio. Every (re)connection to the API is treated as a new connection, and audio is therefore timestamped starting from 00:00:00. However, re-aligning the timestamps correctly to the audio stream is a critical task when restarting an interrupted streaming session.

In this case, the application will need to provide a starting timestamp to offset all hypotheses timings by adding start_ts as a query parameter to the connection request. This will ensure that output hypotheses have their timestamps offset by the number of seconds provided in the start_ts parameter.

Technical approach

The following example can be used to configure a streaming client to transcribe a long-duration stream using a RAW-format audio file. It handles reconnects (whether due to session length timeouts or other connectivity interruption) without losing audio. It also re-aligns timestamp offsets to the new streaming session when reconnecting.

To use this example, replace the <FILEPATH> placeholder with the path to the audio file (RAW format) you wish to stream and the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI account's access token.

const fs = require('fs');
const revai = require('revai-node-sdk');
const { Writable } = require('stream');

const token = '<REVAI_ACCESS_TOKEN>';
const filePath = '<FILEPATH>';
const bytesPerSample = 2;
const samplesPerSecond = 16000;
const chunkSize = 8000;

// initialize client with audio configuration and access token
const audioConfig = new revai.AudioConfig(
    /* contentType */ 'audio/x-raw',
    /* layout */      'interleaved',
    /* sample rate */ samplesPerSecond,
    /* format */      'S16LE',
    /* channels */    1
);

// optional config to be provided.
const sessionConfig = new revai.SessionConfig(
    metadata='example metadata', /* (optional) metadata */
    customVocabularyID=null,  /* (optional) custom_vocabulary_id */
    filterProfanity=false,    /* (optional) filter_profanity */
    removeDisfluencies=false, /* (optional) remove_disfluencies */
    deleteAfterSeconds=0,     /* (optional) delete_after_seconds */
    startTs=0,                /* (optional) start_ts */
    transcriber='machine',    /* (optional) transcriber */
    detailedPartials=false    /* (optional) detailed_partials */
);

// begin streaming session
let client = null;
let revaiStream = null;

let audioBackup = [];
let audioBackupCopy = [];
let newStream = true;
let lastResultEndTsReceived = 0.0;

function handleData(data) {
    switch (data.type){
        case 'connected':
            console.log("Received connected");
            break;
        case 'partial':
            console.log(`Partial: ${data.elements.map(x => x.value).join(' ')}`);
            break;
        case 'final':
            console.log(`Final: ${data.elements.map(x => x.value).join('')}`);
            const textElements = data.elements.filter(x => x.type === "text");
            lastResultEndTsReceived = textElements[textElements.length - 1].end_ts;
            console.log(lastResultEndTsReceived * samplesPerSecond * bytesPerSample / 1024);
            break;
        default:
            // all messages from the API are expected to be one of the previous types
            console.error('Received unexpected message');
            break;
    }
}

function startStream() {
    client = new revai.RevAiStreamingClient(token, audioConfig);

    // create event responses
    client.on('close', (code, reason) => {
        console.log(`Connection closed, ${code}: ${reason}`);
        if (code !== 1000 || reason == 'Reached max session lifetime'){
            console.log('Restarting stream');
            restartStream();
        }
        console.log(bytesWritten);
    });
    client.on('httpResponse', code => {
        console.log(`Streaming client received HTTP response with code: ${code}`);
    });
    client.on('connectFailed', error => {
        console.log(`Connection failed with error: ${error}`);
    });
    client.on('connect', connectionMessage => {
        console.log(`Connected with job ID: ${connectionMessage.id}`);
    });

    audioBackup = [];
    sessionConfig.startTs = lastResultEndTsReceived;

    revaiStream = client.start(sessionConfig);
    revaiStream.on('data', data => {
        handleData(data);
    });
    revaiStream.on('end', function () {
        console.log('End of stream');
    });
}

let bytesWritten = 0;

const audioInputStreamTransform = new Writable({
    write(chunk, encoding, next) {
        if (newStream && audioBackupCopy.length !== 0) {
            // approximate math to calculate time of chunks
            const bitsSent = lastResultEndTsReceived * samplesPerSecond * bytesPerSample;
            const chunksSent = Math.floor(bitsSent / chunkSize);
            if (chunksSent !== 0) {
                for (let i = chunksSent; i < audioBackupCopy.length; i++) {
                    revaiStream.write(audioBackupCopy[i][0], audioBackupCopy[i][1]);
                }
            }
            newStream = false;
        }

        audioBackup.push([chunk, encoding]);

        if (revaiStream) {
            revaiStream.write(chunk, encoding);
            bytesWritten += chunk.length;
        }

        next();
    },

    final() {
        if (client && revaiStream) {
            client.end();
            revaiStream.end();
        }
    }
});

function restartStream() {
    if (revaiStream) {
        client.end();
        revaiStream.end();
        revaiStream.removeListener('data', handleData);
        revaiStream = null;
    }

    audioBackupCopy = [];
    audioBackupCopy = audioBackup;

    newStream = true;

    startStream();
}

// read file from disk
let file = fs.createReadStream(filePath);

startStream();

file.on('end', () => {
    chunkInputTransform.end();
})

// array for data left over from chunking writes into chunks of 8000
let leftOverData = null;

const chunkInputTransform = new Writable({
    write(chunk, encoding, next) {
        if (encoding !== 'buffer'){
            console.log(`${encoding} is not buffer, writing directly`);
            audioInputStreamTransform.write(chunk, encoding);
        }
        else {
            let position = 0;

            if (leftOverData != null) {
                let audioChunk = Buffer.alloc(chunkSize);
                const copiedAmount = leftOverData.length;
                console.log(`${copiedAmount} left over, writing with next chunk`);
                leftOverData.copy(audioChunk);
                leftOverData = null;
                chunk.copy(audioChunk, chunkSize - copiedAmount);
                position += chunkSize - copiedAmount;
                audioInputStreamTransform.write(audioChunk, encoding);
            }

            while(chunk.length - position > chunkSize) {
                console.log(`${chunk.length - position} bytes left in chunk, writing with next audioChunk`);
                let audioChunk = Buffer.alloc(chunkSize);
                chunk.copy(audioChunk, 0, position, position+chunkSize);
                position += chunkSize;
                audioInputStreamTransform.write(audioChunk, encoding);
            }

            if (chunk.length > 0) {
                leftOverData = Buffer.alloc(chunk.length - position);
                chunk.copy(leftOverData, 0, position);
            }
        }

        next();
    },

    final() {
        if (leftOverData != null) {
            audioInputStreamTransform.write(leftOverData);
            audioInputStreamTransform.end();
        }
    }
})

// stream the file
file.pipe(chunkInputTransform);

NOTE: This code sample is illustrative and not intended for production use.

The following sections explain this code listing with reference to the specific problems described earlier.

Connection disruption

Refer to the following code segments:

function startStream() {
    client = new revai.RevAiStreamingClient(token, audioConfig);

    client.on('close', (code, reason) => {
        console.log(`Connection closed, ${code}: ${reason}`);
        if (code !== 1000 || reason == 'Reached max session lifetime'){
            console.log('Restarting stream');
            restartStream();
        }
    });

    // ...

    revaiStream = client.start(sessionConfig);

    // ...
}

function restartStream() {
    if (revaiStream) {
        client.end();
        revaiStream.end();
        revaiStream.removeListener('data', handleData);
        revaiStream = null;
    }

    // ...

    newStream = true;

    startStream();
}

The startStream() function creates a new Rev AI streaming client and initializes a streaming session as revAiStream. It also defines an event handler for a WebSocket close event, which could be generated either due to a connectivity failure or due to a stream timeout. This event handler invokes the restartStream() method, which checks if the revaiStream session was correctly terminated and, if not, restarts it.

Data loss

Refer to the following code segments:

let audioBackup = [];
let audioBackupCopy = [];

const audioInputStreamTransform = new Writable({
    write(chunk, encoding, next) {
        if (newStream && audioBackupCopy.length !== 0) {

            // ...

            if (chunksSent !== 0) {
                for (let i = chunksSent; i < audioBackupCopy.length; i++) {
                    revaiStream.write(audioBackupCopy[i][0], audioBackupCopy[i][1]);
                }
            }
            newStream = false;
        }

        audioBackup.push([chunk, encoding]);

        // ...
    },

    // ...
});

function restartStream() {

    // ...

    audioBackupCopy = [];
    audioBackupCopy = audioBackup;

    newStream = true;

    startStream();
}

Here, audioBackup acts as a data store backup for the streamed audio. If a streaming session ends unexpectedly, two things are needed to restart and continue without data loss:

The backup of the audio to resend from, to ensure no data is lost
A new backup for the restarted stream

When a stream is restarted with the restartStream() function, the contents of audioBackup is copied into audioBackupCopy and then cleared in readiness for the new backup. Data is then sent to the revAiStream streaming session from audioBackupCopy.

Timestamp corruption

Refer to the following code segments:

let lastResultEndTsReceived = 0.0;

function startStream() {
    client = new revai.RevAiStreamingClient(token, audioConfig);

    // ...

    sessionConfig.startTs = lastResultEndTsReceived;
    revaiStream = client.start(sessionConfig);
    revaiStream.on('data', data => {
        handleData(data);
    });

    // ...
}

function handleData(data) {
    switch (data.type){

        // ...

        case 'final':
            const textElements = data.elements.filter(x => x.type === "text");
            lastResultEndTsReceived = textElements[textElements.length - 1].end_ts;
            break;

        // ...
    }
}

Here, the lastResultEndTsReceived variable holds the timestamp received, updated continuously with each final hypotheses. When the streaming session restarts, the start_ts parameter is set to the value of lastResultEndTsReceived, to re-align timestamps to the stream audio.

NOTE: One important point to note here is that this could potentially result in some audio getting resent to the API. Since only final hypotheses have timestamps, all audio since the last final hypothesis will be resent which could lead to some small number of words being duplicated.

Next steps

Transcribing live audio comes with numerous challenges around connection recovery, data protection and timestamp alignment. For developers working with Rev AI's Streaming Speech-to-Text API, this tutorial provided a technical approach and sample implementation to resolve these challenges.

Learn more about the topics discussed in this tutorial by visiting the following links:

Documentation: Streaming Speech-to-Text API overview and code samples
Documentation: Streaming Speech-to-Text example session
Documentation: Node SDK
Tutorial: Best Practices for the Rev AI APIs

Integrate Rev AI's Sentiment Analysis API with a Node.js Application

Vikram Vaswani — Thu, 21 Apr 2022 19:43:36 +0000

By Vikram Vaswani, Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/integrate-sentiment-analysis-api-nodejs/ on Apr 19, 2022.

Introduction

Sentiment analysis attempts to identify the emotional content in a text document and qualify it as positive, negative, or neutral. It is useful in a number of different scenarios, including

Tracking customer support satisfaction levels from customer agent interactions or written complaints
Analyzing political sentiment based on reactions to public speeches
Understanding student engagement and attitudes in class
Scoring leads based on sales team member interactions with prospects
Understanding witness attitudes in depositions

Rev AI offers a Sentiment Analysis API that provides additional speech insights by analyzing sentiments in a given transcript. As an application developer, you can use this API to obtain qualitative information about the feelings expressed in a transcribed conversation and then build applications to act on those insights.

This tutorial explains how to integrate the Rev AI Sentiment Analysis API into your Node.js application.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have a properly-configured Node.js development environment with Node.js v16.x or v17.x. If not, download and install Node.js for your operating system.
You have a JSON transcript generated from the Asynchronous Speech-to-Text API. If not, use this example JSON transcript.

NOTE: The Sentiment Analysis API is under active development. Always refer to the API documentation for the most up-to-date information.

Step 1: Install Axios

The Sentiment Analysis API is a REST API and, as such, you will need an HTTP client to interact with it. This tutorial uses Axios, a popular Promise-based HTTP client for Node.js.

Begin by installing Axios into your application directory:

npm install axios

Within your application code, initialize Axios as below:

const axios = require('axios');
const token = '<REVAI_ACCESS_TOKEN>';

// create a client
const http = axios.create({
  baseURL: 'https://api.rev.ai/sentiment_analysis/v1beta/',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

Here, the Axios HTTP client is initialized with the base endpoint for the Sentiment Analysis API, which is https://api.rev.ai/sentiment_analysis/v1beta/.

Every request to the API must be in JSON format and must include an Authorization header containing your API access token. The code shown above also attaches these required headers to the client.

Step 2: Submit transcript for sentiment analysis

To perform sentiment analysis on a transcript, you must begin by submitting an HTTP POST request containing the transcript content, in either plaintext or JSON, to the API endpoint at https://api.rev.ai/sentiment_analysis/v1beta/jobs.

The code listings below perform this operation using the HTTP client initialized in Step 1, for both plaintext and JSON transcripts:

const submitSentimentAnalysisJobText = async (textData) => {
  return await http.post(`jobs`,
    JSON.stringify({
      text: textData
    }))
    .then(response => response.data)
    .catch(console.error);
};

const submitSentimentAnalysisJobJson = async (jsonData) => {
  return await http.post(`jobs`,
    JSON.stringify({
      json: jsonData
    }))
    .then(response => response.data)
    .catch(console.error);
};

If you were to inspect the return value of the functions shown above, here is an example of what you would see:

{
  id: 'Sz6Fc4g6CqDM',
  created_on: '2022-03-04T06:49:44.049Z',
  status: 'in_progress',
  type: 'sentiment_analysis'
}

The API response contains a job identifier (id field). This job identifier will be required to check the job status and obtain the job result.

Learn more about submitting a sentiment analysis job in the API reference guide.

Step 3: Check job status

Sentiment analysis jobs usually complete within 10-20 seconds. To check the status of the job, you must submit an HTTP GET request to the API endpoint at https://api.rev.ai/sentiment_analysis/v1beta/jobs/<ID>, where <ID> is a placeholder for the job identifier.

The code listing below demonstrates this operation:

const getSentimentAnalysisJobStatus = async (jobId) => {
  return await http.get(`jobs/${jobId}`)
    .then(response => response.data)
    .catch(console.error);
};

Here is an example of the API response to the previous request after the job has completed:

{
  id: 'Sz6Fc4g6CqDM',
  created_on: '2022-03-04T06:49:44.049Z',
  completed_on: '2022-03-04T06:49:49.472Z',
  word_count: 3,
  status: 'completed',
  type: 'sentiment_analysis'
}

Learn more about retrieving the status of a sentiment analysis job in the API reference guide.

Step 4: Retrieve sentiment analysis report

Once the sentiment analysis job's status changes to completed, you can retrieve the results by submitting an HTTP GET request to the API endpoint at https://api.rev.ai/sentiment_analysis/v1beta/jobs/<ID>/result, where <ID> is a placeholder for the job identifier.

The code listing below demonstrates this operation:

const getSentimentAnalysisJobResult = async (jobId) => {
  return await http.get(`jobs/${jobId}/result`,
    { headers: { 'Accept': 'application/vnd.rev.sentiment.v1.0+json' } })
    .then(response => response.data)
    .catch(console.error);
};

If the job status is completed, the return value of the above function is a JSON-encoded response containing a sentence-wise sentiment analysis report. If the job status is not completed, the function will return an error instead.

Here is an example of the sentiment analysis report returned from a completed job:

{
  messages: [
    {
      content: 'I dislike tabs in code.',
      score: -0.801,
      sentiment: 'negative',
      offset: 0,
      length: 23
    },
    ...
  ]
}

It’s also possible to filter the result set to return only positive, negative, or neutral messages by adding a filter_for query parameter to the request.

Learn more about obtaining a sentiment analysis report in the API reference guide.

Step 5: Create and test a simple application

Using the code samples shown previously, it's possible to create a simple application that accepts a plaintext document and returns its sentiment, as shown below:

const main = async (textData) => {
  const job = await submitSentimentAnalysisJobText(textData);
  console.log(`Job submitted with id: ${job.id}`);

  await new Promise((resolve, reject) => {
    const interval = setInterval(() => {
      getSentimentAnalysisJobStatus(job.id)
        .then(r => {
          console.log(`Job status: ${r.status}`);
          if (r.status !== 'in_progress') {
            clearInterval(interval);
            resolve(r);
          }
        })
        .catch(e => {
          clearInterval(interval);
          reject(e);
        });
    }, 15000);
  });

  const jobResult = await getSentimentAnalysisJobResult(job.id);
  console.log(jobResult);
};

main("I dislike tabs in code. But I love jam on toast.");

This example application begins by invoking the main() function with two sentences of text, representing the input to be analyzed. The main() function first submits this data to the Sentiment Analysis API using the submitSentimentAnalysisJobText() method. It then uses setInterval() to repeatedly poll the API every 15 seconds to obtain the status of the job. Once the job status is no longer in_progress, it uses the getSentimentAnalysisJobResult() method to retrieve the job result and prints it to the console.

Here is an example of the output returned by the code above:

  messages: [
    {
      content: 'I dislike tabs in code.',
      score: -0.801,
      sentiment: 'negative',
      offset: 0,
      length: 23
    },
    {
      content: 'But I love jam on toast.',
      score: 0.6,
      sentiment: 'positive',
      offset: 24,
      length: 24
    }
  ]
}

NOTE: The code listing above polls the API repeatedly to check the status of the sentiment analysis job. This is presented only for illustrative purposes and is strongly recommended against in production scenarios. For production scenarios, use webhooks to asynchronously receive notifications once the sentiment analysis job completes.

Next steps

Learn more about the topics discussed in this tutorial by visiting the following links:

Documentation: Sentiment Analysis API reference
Documentation: Sentiment Analysis API webhooks
Tutorial: Get Started with Sentiment Analysis
Tutorial: Get Started with Rev AI Webhooks

Get Started with Rev AI API Webhooks

Vikram Vaswani — Fri, 08 Apr 2022 15:37:10 +0000

By Vikram Vaswani - Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/get-started-api-webhooks/ on Mar 23, 2022.

Introduction

If you've used GitHub, PayPal, Slack or any number of other online services, you've already heard of (and maybe even used) webhooks. Webhooks provide an easy way for one application to notify another about a specific event - for example, a Git commit, a PayPal order or a Slack message - so that the notified application can take further action as needed.

Webhooks are a key component of building event-driven Web applications, and they're also well-supported in the various Rev AI ASR APIs. They provide a simple and efficient approach to programmatically managing job requests submitted through the Rev AI APIs.

Here's how it works:

An application submits a job to a Rev AI API for processing, supplying a webhook URL in the callback_url parameter.
Once job processing is complete, the API sends an HTTP POST message to the webhook URL containing the results of processing.
The webhook URL handler receives the HTTP POST request, parses the request body and implements further application-specific business logic as needed.

When developing event-driven ASR applications, it's important to be able to easily test and inspect the data structures received from the Rev AI APIs. A number of freely-available third-party tools and websites are available for webhook testing, including Webhook.site and RequestBin. This tutorial uses Webhook.site, but the procedure is broadly similar for other alternatives as well.

Assumptions

This tutorial assumes that:

You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
You have an audio file to transcribe. If not, use this example audio file from Rev AI.

Step 1: Obtain a webhook URL

The first step is to obtain a unique webhook URL, which you can do by visiting https://webhook.site/ and copying the URL shown on the page.

This webhook URL will remain active and waiting for requests for so long as you remain on the page.

Step 2: Add the webhook as `callback_url` in your API request

Submit an audio file for transcription to Rev AI using the command below. Replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI access token and the <WEBHOOK_URL> placeholder with the webhook URL obtained in Step 1. If you wish to use a different audio file, additionally replace the value of the media_url parameter with the URL to your audio file.

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"media_url":"https://www.rev.ai/FTC_Sample_1.mp3","callback_url":"<WEBHOOK_URL>"}'

Your API call will return a response like this:

{
  "id":"8xBckmk6rAqu",
  "created_on":"2022-03-16T14:26:14.151Z",
  "name":"FTC_Sample_1.mp3",
  "callback_url":"https://webhook.site/84de11c2-e60b-4c15-928d-969cd26ce3cc",
  "media_url":"https://www.rev.ai/FTC_Sample_1.mp3",
  "status":"in_progress",
  "type":"async",
  "language":"en"
}

Step 3: Inspect the API response

For asynchronous transcription, the job's turnaround time is a function of the audio length. Files that are approximately 5 minutes in length will be returned within a few minutes. Longer files can take up to 15 minutes. Learn more about turnaround time.

Once the job's status changes, the Rev AI API will submit an HTTP POST request to the configured webhook URL. Here is an example of the POST message body:

{
  "job": {
    "id": "8xBckmk6rAqu",
    "created_on": "2022-03-16T14:26:14.151Z",
    "completed_on": "2022-03-16T14:26:53.601Z",
    "name": "FTC_Sample_1.mp3",
    "callback_url": "https://webhook.site/84de11c2-e60b-4c15-928d-969cd26ce3cc",
    "media_url": "https://www.rev.ai/FTC_Sample_1.mp3",
    "status": "transcribed",
    "duration_seconds": 107,
    "type": "async",
    "language": "en"
  }
}

This request to the webhook URL will be visible in the Webhook.site interface, which will auto-refresh to display the complete POST request details as shown below:

As the example above illustrates, the HTTP POST message includes the job identifier and detailed information on the job status, duration and completion time. This information can be used by the application for further decision-making or action, such as:

Recording the job status in a database or message queue
Invoking behavior (for example, an email or SMS notification) prompting additional user action
Retrieving the transcript data
Redirecting the message data to another system for further analysis and processing

Next steps

Webhooks provide a way to asynchronously receive notifications once a Rev AI job completes. Although optional, they are recommended in production environments, as they are significantly more efficient than repeatedly polling the API for job status and also relatively easy to understand and work with.

Learn more about Rev AI APIs and their support for webhooks by visiting the following links:

Tutorial: Use Webhooks to Trigger Job Email Notifications with Node.js, Sendgrid and Express
Documentation: Asynchronous Speech-To-Text API job submission and webhooks
Documentation: Sentiment Analysis API job submission and webhooks
Documentation: Topic Extraction API job submission and webhooks
Documentation: Custom Vocabulary API submission and webhooks