Real-Time Caption Ingestion - API for posting captions to a URL

Overview

StreamText.Net provides a way for 3rd parties to directly ingest real-time text by receiving HTTP requests that include the text content. This article details the specifics of the HTTP request that is sent from the StreamText.Net servers to the 3rd party server for ingestion.

Providing a Caption URL

The only configuration parameter needed is a URL where the StreamText.Net servers will send the HTTP request. Any URL that is reachable on the public internet is valid. Each request will have a `seq` and a `lang` query string parameter appended to the URL when making the request. The `seq` parameter is the integer value current sequence (starting at 1) that is being sent.

HTTP Request Message

The StreamText.Net servers will send an HTTP POST message to the provided Caption URL after appending the `seq` and `lang` values. The `Content-Type` of the POST message will be plain text and will include all of the content since the last successful message was sent. NOTE: The content will be a UTF-8 string and may include non printable characters such as spaces, tabs, line feeds, carriage returns, and most importantly delete. The service receiving these message should think of the HTTP messages and the corresponding content as a stream and will be responsible for processing the delete characters against previous characters that were sent.

An example HTTP POST message

POST /caption-url?param1=value1&param2=value2&seq=1&lang=en
Host: host-name-in-caption-url
Content-Type: text/plain; charset=utf-8
Content-Length: 52
Content-Language: en-US
Date: Sat, 20 Jun 2020 16:43:29 GMT
X-Timestamp: 2020-06-20T16:43:29.0960224Z
This is a test\n
With 2 lins\x08es and a delete character

Note: The content `\n` and `\x08` are not literal characters. They are place holders for a line feed byte and a delete byte since those characters can not be represented in a printable form. 

Options for how text is posted to your HTTP endpoint.

1. Word for Word (realtime):  By default the content will include edits by providing sequences of  backspaces encoded in UTF8 . We will post text as soon as we receive it which means it will be small granular chunks of text  Edits will be represented by backspace sequences  that will require you to process these in your interface so edited text can be replaces. By supporting these sequences you can provide realtime captions instead of waiting for a competed line of captions to be sent.

2. Line at a time: You can resort to line for line captions as well if you cannot process these characters in realtime by having the realtime ingestion settings in streamtext set to send complete line. Our interface allows the user to define the line length and a correction buffer if needed to prevent  unprocessed edits from being sent out. 

HTTP Request Headers

• Content-Type: Value will always be `text/plain; charset=utf-8`.
• Content-Length: The length of the text in the body of the request.
• Content-Language: The language of the captions.
• Date: Standard HTTP Date header value or the time the request was generated.
• X-Timestamp: The ISO 8601 representation of the time the content was generated.

Questions and Support

Please contact support at support@streamtext.net with any questions or for any clarifications. We will be happy to set up an account for you so you can test your integration.