Captions and chapters

Edit a video's captions in the browser while it plays, and split it into chapters that viewers jump between from the seek bar. Both are WebVTT, so they work in other players too.

The caption editor

On a video's Captions tab, choose Edit on a caption track, or pick a language and choose Write them in the editor to start a new one. The cues are listed with their start, end and text, beside the video at the top of the page:

  • Click a cue's number to jump the player there. The cue playing now is highlighted, and the list keeps it in view while the video plays.
  • Add cue at adds an empty cue at the playhead, lasting two seconds or until the next cue starts. Split a cue in two (at the playhead when it is inside the cue, otherwise in the middle), delete it, or move its start or end by a tenth of a second with the − and + buttons.
  • Times can be typed as 75.5, 1:15.5 or 1:01:15.250.
  • Undo and redo step through your changes, and Discard changes goes back to the last save. The page warns you before you leave with unsaved changes.
  • A cue that ends before it starts, starts before 0 or has no text stops the save. Overlapping cues are allowed (two people talking at once) but marked.

Saving writes the whole track back as WebVTT. The track keeps its id, so its URL, and pages that use it, carry on working. Cue identifiers and settings (align:start, line:0), cue text with several lines or markup, and NOTE, STYLE and REGION blocks are kept as they were. A block the editor can't read is listed when the track opens and left out when it is saved.

SubRip (.srt) files are converted to WebVTT when you upload them, so you can edit those too.

Replace a caption track

Save new WebVTT for one of a video's caption tracks, keeping its id. The text is stored as a new file (counted as caption storage, like an upload) and the old file is deleted. An edit never counts against your file limit, and only growth over the old text counts against your storage limit (403 storage_limit_reached). It must start with a WEBVTT line, be UTF-8 and at most 512 KB, and every cue must end after it starts, in start time order: otherwise the answer is 400 invalid_vtt, naming the line. Needs your private key. No webhook is sent.

PUT
1
https://api.fileboy.io/videos/{id}/transcripts/{transcriptId}

URL Params

id string

The video id.

transcriptId string

The caption track's id, from the video's transcripts.

Body

vtt string

The whole track as WebVTT.

language string, optional

A new language code for the track, like en-GB. Left out, it keeps its own.

Response

data.id string

The track id, unchanged.

data.fileId string

The new file holding its text.

data.url string

Where players read it.

Example

REQUEST
1
2
3
4
5
curl -X PUT https://api.fileboy.io/videos/VIDEO_ID/transcripts/TRANSCRIPT_ID -H "Authorization: token 0000000...." -H "Content-Type: application/json" -d '{"vtt": "WEBVTT

00:00:01.000 --> 00:00:03.500
Hello and welcome.
"}'
RESPONSE
1
2
3
4
5
6
7
8
9
10
{
  "data": {
    "id": "TRANSCRIPT_ID",
    "videoId": "VIDEO_ID",
    "language": "en",
    "fileId": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b",
    "size": 59,
    "url": "https://api.fileboy.io/videos/VIDEO_ID/transcripts/TRANSCRIPT_ID"
  }
}

Chapters

A chapter is a title and the time it starts. It runs until the next one starts, and the last one to the end of the video. Add them on the video's Captions tab: play to where a section starts and choose Add chapter at, then name it. Most videos start with a chapter at 0:00.

The Fileboy player marks where each chapter starts on its seek bar, and the time over the seek bar says which chapter that moment is in, on the watch and embed pages and with <fileboy-player> 1.4.0 and later. It only fetches chapters for videos that have some: the video's data says so (chapters.count and chapters.vtt, null when there are none). To use your own chapters, or none, set the player's chapters attribute to a WebVTT chapters track's URL, or to off. See Play a video.

For other players, the chapters are a WebVTT chapters track at /videos/ID/chapters.vtt, for <track kind="chapters">. It follows the video's read access like the rest of the video, and is never cached unchecked, so edits show at once.

GET /videos/ID/chapters.vtt
1
2
3
4
5
6
7
8
9
WEBVTT

chapter-1
00:00:00.000 --> 00:01:35.500
Introduction

chapter-2
00:01:35.500 --> 00:05:12.000
The demo

Up to 100 chapters a video, each title 1 to 100 characters, no two at the same time (to the millisecond), and none at or after the end of the video.

Get a video's chapters

The chapters in start time order, [] when there are none. Needs your private key.

GET
1
https://api.fileboy.io/videos/{id}/chapters

URL Params

id string

The video id.

Response

data[].title string

The chapter's title.

data[].startTime number

Seconds from the start.

data[].endTime number | null

When the next chapter starts or the video ends. Null for the last chapter while the video's length isn't known.

Example

REQUEST
1
curl https://api.fileboy.io/videos/VIDEO_ID/chapters -H "Authorization: token 0000000...."
RESPONSE
1
2
3
4
5
6
{
  "data": [
    { "title": "Introduction", "startTime": 0, "endTime": 95.5 },
    { "title": "The demo", "startTime": 95.5, "endTime": 312 }
  ]
}

Set a video's chapters

Replaces the whole list; [] removes them all. They are saved sorted by start time, and a list read with GET can be sent back as it is (endTime is ignored). A bad list is refused with 400 validation_error, saying which chapter and why. Needs your private key.

PUT
1
https://api.fileboy.io/videos/{id}/chapters

URL Params

id string

The video id.

Body

chapters array

Every chapter, each { title, startTime } with startTime in seconds.

Response

data array

The chapters as saved.

Example

REQUEST
1
curl -X PUT https://api.fileboy.io/videos/VIDEO_ID/chapters -H "Authorization: token 0000000...." -H "Content-Type: application/json" -d '{"chapters": [{"title": "Introduction", "startTime": 0}, {"title": "The demo", "startTime": 95.5}]}'
SDKs
1
2
3
4
5
6
7
8
// Node (Ruby, Python and PHP have the same methods in their own style)
await fileboy.setVideoChapters(videoId, [
  { title: "Introduction", startTime: 0 },
  { title: "The demo", startTime: 95.5 },
])
const chapters = await fileboy.getVideoChapters(videoId)

await fileboy.replaceVideoTranscript(videoId, transcriptId, vttText)
RESPONSE
1
2
3
4
5
6
{
  "data": [
    { "title": "Introduction", "startTime": 0, "endTime": 95.5 },
    { "title": "The demo", "startTime": 95.5, "endTime": 312 }
  ]
}