Plum DEV Documentation
plumdevguide:transcription

Transcription Guide

Transcription API Description

Plum offers three services for its Transcription REST API:

Method Service Description
POST transcription/queue Queues an audio file for human assisted transcription and returns a transcription resource.
GET transcription/status Returns a single transcription resource.
POST transcription/transcribe Performs a real-time machine based transcription and immediately returns the result.

Please note that each of the Transcription REST APIs use HTTP AUTH for authentication. Please contact your account manager to get access credentials.

All of the Transcription REST APIs have the same return format that includes a status (success or failure), error message and the result data.

Example Responses:

XML (success):

<sample>
  <status>success</status>
  <error/>
  <result>
    <!-- SAMPLE RESULT DATA -->
  </result>
</sample>

JSON (success):

{
  "status":"success",
  "error":"",
  "result": {
    // SAMPLE RESULT DATA
  }
}

XML (failure):

<sample>
  <status>failure</status>
  <error>Unauthorized access to sample service</error>
</sample>

JSON (failure):

{
  "status":"failure",
  "error":"Unauthorized access to sample service",
}


Queue Transcription REST API (POST transcription/queue)

Queues an audio file for transcription.

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL for XML-formatted Response: https://hosting.plumvoice.com/ws/transcription/queue.xml

Resource URL for JSON-formatted Response: https://hosting.plumvoice.com/ws/transcription/queue.json

Required multipart/form-data POST Parameters:

Parameter Type Description
language string This parameter is reserved for future use, the only currently allowed value is “en-US”.
workflow string This parameter is reserved for future use, the only currently allowed value is “hybrid”.
audio file The audio file that will be transcribed. NOTE: currently only headerless u-law audio is supported.
result_url string URL for receiving the transcription result status
Note: after the transcription is complete this URL will receive a POST with the following variables: 'transcription_id', 'message', 'response_timestamp' and 'status'. This should be used to get the result of an transcription request rather than polling the status REST service.

Example Responses:

XML:

<queue>
  <status>success</status>
  <error/>
  <result>
    <transcription_id>f85bd7682c9f71b60e216f2f6d39e95d</transcription_id>
    <duration>60</duration>
    <language>en-US</language>
    <workflow>hybrid</workflow>
    <request_timestamp>1394776766</request_timestamp>
    <result_url>http://myserver.com/transcription_result.php</result_url>
    <status>queued</status>
  </result>
</queue>

JSON:

{
  "status":"success",
  "error":"",
  "result": {
    "transcription_id":"f85bd7682c9f71b60e216f2f6d39e95d",
    "duration":60,
    "language":"en-US",
    "workflow":"hybrid",
    "request_timestamp":1394776766,
    "result_url":"http://myserver.com/transcription_result.php",
    "status":"queued"
  }
}

Try it out:

parameters
result format
language
workflow
audio NOTE: headerless u-law audio only
result url

VoiceXML Code Example:

transcribe.xml

<?xml version="1.0"?>
<vxml version="2.0">
  <form>
    <record name="recording1" beep="true">
      <prompt bargein="false">Record your message after the beep.</prompt>
    </record>
    <block>
      <var name="language" expr="'en-US'"/>
      <var name="workflow" expr="'hybrid'"/>
      <var name="audio" expr="recording1"/>
      <var name="result_url" expr="'http://myserver.com/transcription_result.php'"/>
      <data name="result" src="https://username:password@hosting.plumvoice.com/ws/transcription/queue.xml" namelist="language workflow audio result_url" method="post" enctype="multipart/form-data"/>
      <if cond="result.documentElement.childNodes.item(0).firstChild.toString() == 'success'">
        <log expr="'transcription_id: '+result.documentElement.childNodes.item(2).firstChild.firstChild.toString()"/>
      <else/>
        <log expr="'error: '+result.documentElement.childNodes.item(1).firstChild.toString()"/>
      </if>
    </block>
  </form>
</vxml>

transcription_result.php:

<?php
// make sure the log file has read/write permissions from the web server
$logfile = "logs/transcription_results.log";
if (!is_readable($logfile) || !is_writable($logfile)) {
  die("Unable to write to log file.");
}

if (isset($_POST['transcription_id'], $_POST['status'])) {
  if ($fp = fopen($logfile, 'a+')) {
    $date = date("r");
    $trascription_id = $_POST['transcription_id'];
    $status = $_POST['status'];
    $message = $_POST['message'];
    fwrite($fp, "$date $transcription_id $status: $message\n");
    fclose($fp);
  }
}
?>

CURL Example from the Command Line:

curl -u username:password -F language=en-US -F workflow=hybrid -F audio=@/path/to/audio -F result_url=http://myserver.com/transcription_result.php https://hosting.plumvoice.com/ws/transcription/queue.xml


Status Transcription REST API (GET transcription/status)

Returns the status of a transcription request.

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL for XML-formatted Response: https://hosting.plumvoice.com/ws/transcription/status.xml/{transcription_id}

Resource URL for JSON-formatted Response: https://hosting.plumvoice.com/ws/transcription/status.json/{transcription_id}

Required Resource Parameters:

Parameter Type Description
transcription_id string Unique 128-bit hexidecimal identifier for this transcription request
Note: this value is provided in the result of a queued transcription request

Example Responses:

XML:

<status>
  <status>success</status>
  <error/>
  <result>
    <transcription_id>f85bd7682c9f71b60e216f2f6d39e95d</transcription_id>
    <message>This is the transcribed text.</message>
    <duration>4</duration>
    <language>en-US</language>
    <workflow>hybrid</workflow>
    <request_timestamp>1394776766</request_timestamp>
    <response_timestamp>1394776767</response_timestamp>
    <result_url>http://myserver.com/transcription_result.php</result_url>
    <status>complete</status>
  </result>
</status>

JSON:

{
  "status":"success",
  "error":"",
  "result": {
    "transcription_id":"f85bd7682c9f71b60e216f2f6d39e95d",
    "message":"This is the transcribed text.",
    "duration":4,
    "language":"en-US",
    "workflow":"hybrid",
    "request_timestamp":1394776766,
    "response_timestamp":1394776767,
    "result_url":"http://myserver.com/transcription_result.php",
    "status":"complete"
  }
}

PHP Code Example:

checkstatus.php

<?php
header("Content-type: text/xml");

// for this example, our transcription_id is f85bd7682c9f71b60e216f2f6d39e95d
$transcription_id = 'f85bd7682c9f71b60e216f2f6d39e95d';

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/transcription/status.xml/".$transcription_message_id);

echo(curl_exec($ch));

curl_close($ch);
?>

CURL Example from the Command Line:

curl -u username:password https://hosting.plumvoice.com/ws/transcription/status.json/f85bd7682c9f71b60e216f2f6d39e95d


Real-time Transcription REST API (POST transcription/transcribe)

Performs real-time transcription of an audio file.

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL for XML-formatted Response: https://hosting.plumvoice.com/ws/transcription/transcribe.xml

Resource URL for JSON-formatted Response: https://hosting.plumvoice.com/ws/transcription/transcribe.json

Required multipart/form-data POST Parameters:

Parameter Type Description
language string The following language codes are supported: en-US, en-GB, es-ES, ja-JP, pt-BR, zh-CN.
audio file The audio file that will be transcribed. NOTE: currently only headerless u-law audio is supported.

Example Responses:

XML:

<?xml version="1.0"?>
<transcribe>
  <status>success</status>
  <error></error>
  <result>
    <transcription_id>0ddc6c6f313b45b6a8b28640b679e602</transcription_id>
    <message>This is the transcribed text.</message>
    <duration>4</duration>
    <language>en-US</language>
    <workflow>auto</workflow>
    <request_timestamp>1531227497</request_timestamp>
    <response_timestamp>1531227498</response_timestamp>
    <status>complete</status>
  </result>
</transcribe>

JSON:

{
  "status":"success",
  "error":"",
  "result": {
    "transcription_id":"0ddc6c6f313b45b6a8b28640b679e602",
    "message":"This is the transcribed text.",
    "duration":4,
    "language":"en-US",
    "workflow":"auto",
    "request_timestamp":1531227497,
    "response_timestamp":1531227498,
    "status":"complete"
  }
}

Try it out:

parameters
result format
language
audio NOTE: headerless u-law audio only

VoiceXML Code Example:

transcribe.xml

<?xml version="1.0"?>
<vxml version="2.0">
  <form>
    <record name="recording1" beep="true">
      <prompt bargein="false">Record your message after the beep.</prompt>
    </record>
    <block>
      <var name="language" expr="'en-US'"/>
      <var name="audio" expr="recording1"/>
      <data name="transcribe" src="https://username:password@hosting.plumvoice.com/ws/transcription/transcribe.json" namelist="language audio" method="post" enctype="multipart/form-data" accept="application/json"/>
      <if cond="transcribe.status == 'success'">
        <log expr="'transcription_id: '+transcribe.result.transcription_id"/>
        <prompt>You said: <value expr="transcribe.result.message"/></prompt>
      <else/>
        <log expr="'error: '+transcribe.error"/>
      </if>
    </block>
  </form>
</vxml>

CURL Example from the Command Line:

curl -u username:password -F language=en-US -F audio=@/path/to/audio https://hosting.plumvoice.com/ws/transcription/transcribe.json