RESTful API Workflow Integration Checklist

This checklist provides detailed steps for partners setting up an integration with CaptionSync using the CaptionSync RESTful API. An overview of the flow for existing integrations is available.

NOTE: Attached at the end of this article, there are media samples that you can use with our caption outputs. Please open a Support ticket to request specific samples of caption outputs.

1. To develop and test an integration, you'll need to use your CaptionSync developer account. This article assumes you have already created your account with us. If not, check out our article on creating a developer account (first paragraph).

2. We will provide you with a customer shared secret to use with your test account for API access. In a deployed integration, users would retrieve a shared secret from the CaptionSync UI, similar to this:

3. Choose a value for the PartnerType field in API calls, and use it for all submissions. This tag allows CaptionSync to track submissions from your platform, and check that the preferred output formats for your platform have been generated. It should indicate the name of your company or product, such as AlphaVideoServer. Please add this as a comment on your existing integration Support ticket. *** This value needs to be approved by AST before it can be used ***

4. Choose a standard input format(s) for the media files. If the platform transcodes video it is generally best to agree on one or two codecs and container formats that will be ingested by AST for all customer captioning requests. For example, a low bitrate MP4 for videos. If transcoding or editing is performed on the file after the original customer video is uploaded or recorded, please ensure that the file provided to AST has the same duration and timecodes as the video(s) that will ultimately be streamed to viewers. If customers have the ability to edit videos after upload/recording, the best practice is to prevent further editing after a caption request has been submitted. You can note these formats on your integration ticket as well.

5. Choose a preferred caption output format. We support several output formats, and new ones are constantly being developed and added. The most popular formats are DFXP with begin/end tags (.DFXP.XML) and WebVTT (2014.vtt). When it is one of the options for the platform's players, AST recommends DFXP, as it has more robust styling and character encoding options than SRT or WebVTT, but WebVTT is becoming the preferred caption format for captions on mobile devices. Please note your preferred output format on your integration ticket. You can have more than one output per submission (e.g. .DFXP.XML and .CLEAN.TXT). If you are using the callback method, you may optionally specify a MIME type for each output type, or a macro in the URL to differentiate between the different outputs.

6. Perform a test submission, using the CaptionSync_Sample.mp4 test video file below. You'll need to make the video file available on your platform, and then provide a full URL as the URL parameter of the create method (see Section 3.2 of the REST API documentation for details). 

7. Some manual intervention is required on our side when submitting test requests, so the output captions will not be available immediately, especially if the submission is made outside of normal business hours (Pacific time zone). However, the test files above are already transcribed, so response should be fairly quick within business hours.

8. CaptionSync will POST the output files to the callback URL that you designated in your create call above.

9. Test your callback handler independently using the WebVTT sample file attached at the end of this article. Note that CaptionSync will hit the callback URL with a single part "raw" POST for each output type with the outputs in the body (content) of the POST. Your callback handler should be able to handle subsequent updates to the caption file for a particular submission. This happens when a customer requests an update to the transcript or caption file using the CaptionSync redo feature (see notes below). Below is sample code in PHP for a callback handler:

$postdata = file_get_contents("php://input");
// check valid id value or db dip to get mapping from id to filename
$cap_fn=$mypath."/".$_GET['id'].".vtt";
if (!$handle = fopen($cap_fn, 'w'))
  trigger_error("Internal fopen error! Could not open file ".$cap_fn.".");
if (fwrite($handle, $postdata) === FALSE)
  trigger_error("Internal fwrite error! Could not write file ".$cap_fn.".");

You can also test your callback handler and simulate AST callbacks using cURL, with something like:

curl --raw -L -X POST -H 'Content-Type: text/xml' --data-binary
@CaptionSync_Sample.2014.vtt https://yourcallbackURL.com

Those are the setup steps for testing most integrations. Other points to consider include:

• It is best-practice to include a "Notes to transcriber" field in your caption request submission UI. This allows the customer to include notes about the particular lecture or video at time of submission. For example, technical terms, spelling of proper names, etc. It is also possible for customers to setup a "Persistent transcriber note" for any account via the CaptionSync web interface (these notes will be routed to transcribers with every submission on the account).

• Be sure to incorporate cross-checks that prevent users from accidentally submitting duplicate caption requests. For example, before sending a file to CaptionSync, check to see if there are already captions associated with the video, or if a previous request has been submitted and you are awaiting results. In cases where a user may need to re-submit a video, you will want to have a way to reset the status to "uncaptioned". Similarly, if you allow users to copy or clone recordings, the status of captions and caption requests should also be copied to the new video.

• If you are using callbacks to receive caption files, your caption callback handler should be able to receive updates to the caption file for a particular submission. The reasons for this are: a) CaptionSync users may do free "redos", which allow them to update the transcription and subsequent caption files, and b) in case the first caption file is incomplete or corrupt the problem can be requested by a second POST of the caption file using your callback URL for the submission.

• It is best practice to include the app parameter in your create calls. This parameter indicates whether the submission is for captioning (you want to receive a closed caption file with caption timing data back), transcription (you only need a .txt transcript), or production transcripts. If this parameter is not included, CaptionSync will use the default settings on the user's CaptionSync account.

• Setting up a status callback handler, as described in the API documents, allows you to supplement state information that you store in your database based on your own workflow actions with additional status updates provided by AST.

• It is possible to allow customers to upload a transcript that corresponds to the video and then request only the synchronized caption output, rather than full transcription and captioning services. We can provide specifics on how to implement this feature if desired.

Please refer to these documents for additional examples:

• Workflow Integrations Overview
• RESTful API Documentation
• Video Player Accessibility Considerations

Test Files:

Use the following sample files for testing purposes: