Segments
Each content item can have multiple segments. For instance, an article typically includes a title, a summary and a body. The body itself typically contains multiple paragraphs, which may include multimedia elements such as images, audio clips, and videos. These individual components are referred to as segments. Segmenting content enables flexibility, allowing for a range of features when combined with the BeyondWords Player. These include skipping between segments, initiating playback from specific segments (e.g., clicking play on a paragraph), and highlighting segments during playback (e.g., paragraph highlighting as it plays).
You have three options when it comes to generating audio: auto_segment, manual_segment, or audio_upload.
auto_segment
We recommend the auto_segment option for publishers seeking a simple way to generate audio versions of their articles.
To use this option set type property to auto_segment whenever you create or update a content item.
Using this option, you are required to submit data for the body property, with the title and summary properties being optional additions.
Once submitted, BeyondWords will automatically segment the body data into segments. In the initial response, the segments will be an empty array, as automatic segmenting is an asynchronous operation. However, once the audio has been generated and you retrieve a content item using the ?segments=full query parameter, you will be able to view the individual segments.
Example request and responses:
{
"type": "auto_segment",
"title": "<h1>Your content title text</h1>",
"summary": "<h2>Your content summary text</h2>",
"body": "<p>Your content body text</p>",
"source_id": "article-id-in-your-cms",
"source_url": "https://example.com/some-article",
"author": "Steve Jobs",
"image_url": "https://example.com/image.jpeg",
"metadata": {
"key": "value"
},
"published": true,
"publish_date": null,
"ads_enabled": true,
"auto_segment_updates_enabled": true
}
{
"type": "auto_segment",
"status": "queued",
"id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
"title": "<h1>Your content title text</h1>",
"summary": "<h2>Your content summary text</h2>",
"body": "<p>Your content body text</p>",
"source_id": "article-id-in-your-cms",
"source_url": "https://example.com/some-article",
"author": "Steve Jobs",
"image_url": "https://example.com/image.jpeg",
"audio": [],
"video": [],
"segments": [],
"is_copy": false,
"ads_enabled": true,
"title_voice_id": null,
"summary_voice_id": null,
"body_voice_id": null,
"metadata": {
"key": "value"
},
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z",
"published": true,
"publish_date": "2023-01-01T00:00:00Z",
"auto_segment_updates_enabled": true
}
{
"type": "auto_segment",
"status": "processed",
"id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
"title": "<h1>Your content title text</h1>",
"summary": "<h2>Your content summary text</h2>",
"body": "<p>Your content body text</p>",
"source_id": "article-id-in-your-cms",
"source_url": "https://example.com/some-article",
"author": "Steve Jobs",
"image_url": "https://example.com/image.jpeg",
"audio": [
{
"id": 36553942,
"content_type": "application/x-mpegURL",
"url": "https://example.com/media.m3u8",
"duration": 7051
},
{
"id": 36553929,
"content_type": "audio/mpeg",
"url": "https://example.com/media_compiled.mp3",
"duration": 7056
}
],
"video": [],
"segments": [
{
"marker": "0a2bae2e-542f-498e-95c4-91dfc403eb8b",
"section": "title",
"start_time": 45,
"duration": 1730,
"id": 95737414,
"content_type": "text",
"text": "Your content title text",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English (USA)"
},
"voice": {
"id": 298,
"name": "Matthew"
},
"created": "2023-07-26T05:02:24Z",
"updated": "2023-07-26T05:02:25Z"
},
{
"marker": "b012ad1b-7366-4ed1-a6f2-b855665065ad",
"section": "summary",
"start_time": null,
"duration": null,
"id": 95737415,
"content_type": "text",
"text": "Your content summary text",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English (USA)"
},
"voice": {
"id": 776,
"name": "Sara"
},
"created": "2023-07-26T05:02:24Z",
"updated": "2023-07-26T05:02:25Z"
},
{
"marker": "ad212f8f-8356-4059-9ee9-c5b1406f70b7",
"section": "body",
"start_time": 1841,
"duration": 2595,
"id": 95737416,
"content_type": "text",
"text": "Your content summary text",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English (USA)"
},
"voice": {
"id": 776,
"name": "Sara"
},
"created": "2023-07-26T05:02:24Z",
"updated": "2023-07-26T05:02:25Z"
},
{
"marker": "76bfc232-2755-4da7-86b1-222a66434444",
"section": "body",
"start_time": 4503,
"duration": 2559,
"id": 95737417,
"content_type": "text",
"text": "Your content body text",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English (USA)"
},
"voice": {
"id": 776,
"name": "Sara"
},
"created": "2023-07-26T05:02:24Z",
"updated": "2023-07-26T05:02:25Z"
}
],
"ads_enabled": true,
"is_copy": false,
"title_voice_id": null,
"summary_voice_id": null,
"body_voice_id": null,
"metadata": {
"key": "value"
},
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z",
"published": true,
"publish_date": "2023-01-01T00:00:00Z",
"auto_segment_updates_enabled": true
}
manual_segment
We recommend the manual_segment option for publishers seeking enhanced control over the audio conversion of their content. This is particularly beneficial for those who wish to integrate the content API into their editorial interface or create videos with multiple images (coming soon).
To use this option set type property to manual_segment whenever you create or update a content item.
Using this option, you should not submit any data to the title, body or summary properties.
Instead, you will need to submit an array of one or multiple segments.
For each segment you submit you will need to submit data to the following properties:
| Property | Options |
|---|---|
section | Use this property define the section type of a segment as either title, summary or body. |
content_type | If content_type is text then submit plain text to be converted into audio. If no voice_id is submitted then the audio will be generated with the default project voices assigned title, summary or body in the project. |
If content_type is audio then submit an audio_url to be uploaded. | |
If content_type is image then submit an image_url to be uploaded. |
Once submitted, BeyondWords will generate the audio for segments with text and then concatenate all segments into a single audio.
Text and audio will be included in generated audios and text, audio and images will be included in generated videos (coming soon).
Example request and responses:
{
"type": "manual_segment",
"source_id": "example-source-id",
"source_url": "https://example.com/some-article",
"author": "Steve Jobs",
"image_url": "https://example.com/image.jpeg",
"metadata": {
"key": "value"
},
"segments": [
{
"section": "title",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is a title",
"voice": {
"id": 1
}
},
{
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a2",
"content_type": "text",
"text": "This is a paragraph",
"voice": {
"id": 1
}
},
{
"section": "body",
"content_type": "image",
"image_url": "https://example.com/image.jpeg"
},
{
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6311a5",
"content_type": "text",
"text": "This is another paragraph",
"voice": {
"id": 1
}
},
{
"section": "body",
"marker": "75aa616c-1849-4d71-bb3b-7691cc6310a5",
"content_type": "audio",
"audio_url": "https://example.com/audio.mp3"
},
{
"section": "body",
"marker": "75aa416c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is another paragraph",
"voice": {
"id": 1
}
}
],
"published": true,
"ads_enabled": false,
"auto_segment_updates_enabled": false
}
{
"id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
"status": "processed",
"type": "manual_segment",
"title": null,
"summary": null,
"body": null,
"source_id": "example-source-id",
"source_url": "https://example.com/some-article",
"author": "Steve Jobs",
"image_url": "https://example.com/image.jpeg",
"metadata": {
"key": "value"
},
"audio": [
{
"id": 1,
"content_type": "application/vnd.apple.mpegurl",
"url": "https://example.com/audio.m3u8",
"duration": 10000
},
{
"id": 2,
"content_type": "audio/mpeg,",
"url": "https://example.com/audio.mp3",
"duration": 10000
}
],
"video": [],
"segments": [
{
"id": 1,
"section": "title",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is a title",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 2,
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a2",
"content_type": "text",
"text": "This is a paragraph",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 3,
"section": "body",
"content_type": "image",
"text": null,
"audio_url": null,
"image_url": "https://example.com/image.jpeg",
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 4,
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6311a5",
"content_type": "text",
"text": "This is another paragraph",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 5,
"section": "body",
"marker": "75aa616c-1849-4d71-bb3b-7691cc6310a5",
"content_type": "audio",
"text": null,
"audio_url": "https://example.com/image.mp3",
"image_url": null,
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 6,
"section": "body",
"marker": "75aa416c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is another paragraph",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
}
],
"ads_enabled": true,
"auto_segment_updates_enabled": true,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
}
audio_upload
We recommend audio_upload option for publishers that want to host podcasts or human-recorded articles on BeyondWords and leverage the BeyondWords Player, podcast feeds and analytics.
To use this option set the type property to audio_upload whenever you create or update a content item.
Using this option, you should submit a title, body and segments array with a single segment object with section set to title, content_type set to audio and an audio_url with a URL to the audio file to be upload.
The title and body text will not be converted into audio. However the text may be present in the player or podcast feeds depending on your player or playlist settings.
Example request:
{
"type": "audio_upload",
"title": "Podcast episode title",
"body": "Podcast episode description",
"source_id": "example-source-id",
"source_url": "https://example.com/some-article",
"author": "Harry Stebbings",
"image_url": "https://example.com/image.jpeg",
"metadata": {
"key": "value"
},
"segments": [
{
"section": "title",
"content_type": "audio",
"audio_url": "https://example.com/audio.mp3"
}
],
"published": true,
"ads_enabled": true,
"auto_segment_updates_enabled": false
}