API reference

GET /api/v1/projects

GET /api/v1/projects

Answers

GET /api/v1/projects/{project}

GET /api/v1/projects/{project}

Parameters

Answers

A sentence: its text, its lines and their takes

GET /api/v1/projects/{project}/sentences/{sentence}

Needs the editor role · operationId read-sentence

Parameters

Answers

A sentence's earlier versions, a page

GET /api/v1/projects/{project}/sentences/{sentence}/history

Needs the editor role · operationId read-sentence-history

Parameters

Answers

The changes kept in the history, newest first, a page

GET /api/v1/projects/{project}/history

Needs the editor role · operationId read-history

Parameters

Answers

A word: how it is said, and its respelling

GET /api/v1/projects/{project}/words/{word}

Needs the editor role · operationId read-word

Parameters

Answers

Other lines' readings of a line's words

GET /api/v1/projects/{project}/lines/{line}/borrow-sources

Needs the editor role · operationId list-borrow-sources

Parameters

Answers

The cast's characters

GET /api/v1/projects/{project}/characters

Needs the editor role · operationId list-characters

Parameters

Answers

One character

GET /api/v1/projects/{project}/characters/{character}

Needs the editor role · operationId read-character

Parameters

Answers

The project's settings

GET /api/v1/projects/{project}/settings

Needs the editor role · operationId read-settings

Parameters

Answers

POST /api/v1/projects/{project}/changes

POST /api/v1/projects/{project}/changes

Deprecated

Use the commands; this goes once the studio's page does

Parameters

Body

ChangeAsk.

Answers

GET /api/v1/projects/{project}/commands

GET /api/v1/projects/{project}/commands

Parameters

Answers

Add a character to the cast

POST /api/v1/projects/{project}/commands/add-character

Needs the editor role · Cost: edit · operationId add-character

Add a character named name to the cast, with how it should sound, which its voice is designed from.

Parameters

Body

NewCharacter.

Answers

Rename a character

POST /api/v1/projects/{project}/commands/rename-character

Needs the editor role · Cost: edit · operationId rename-character

Give a character a new name.

Parameters

Body

RenameCharacter.

Answers

Say who a character is

POST /api/v1/projects/{project}/commands/describe-character

Needs the editor role · Cost: edit · operationId describe-character

Say who a character is, for the cast and the voice it is given.

Parameters

Body

DescribeCharacter.

Answers

Say how a character should sound

POST /api/v1/projects/{project}/commands/set-voice-description

Needs the editor role · Cost: edit · operationId set-voice-description

Say how a character should sound, for designing its voice.

Parameters

Body

SetVoiceDescription.

Answers

Make a character a group said at once by these members, or one character again

POST /api/v1/projects/{project}/commands/set-group-members

Needs the editor role · Cost: edit · operationId set-group-members

Make a character a group said by these characters at once, adding any new ones named; no members makes it one character again.

Parameters

Body

SetGroupMembers.

Answers

For a group: whether the narrator reads its lines instead

POST /api/v1/projects/{project}/commands/set-narrator-reads

Needs the editor role · Cost: edit · operationId set-narrator-reads

For a group: whether the narrator reads its lines instead.

Parameters

Body

SetNarratorReads.

Answers

For a group: how loosely its members keep together

POST /api/v1/projects/{project}/commands/set-group-spread

Needs the editor role · Cost: edit · operationId set-group-spread

For a group: how loosely its members keep together.

Parameters

Body

SetGroupSpread.

Answers

For a group: keep in step word by word or over the whole line

POST /api/v1/projects/{project}/commands/set-group-sync

Needs the editor role · Cost: edit · operationId set-group-sync

For a group: whether its members keep in step word by word or over the whole line.

Parameters

Body

SetGroupSync.

Answers

For a group: the member the others follow

POST /api/v1/projects/{project}/commands/set-group-lead

Needs the editor role · Cost: edit · operationId set-group-lead

For a group: the member the others follow.

Parameters

Body

SetGroupLead.

Answers

For a group: when one member starts and how loud it is

POST /api/v1/projects/{project}/commands/set-member-mix

Needs the editor role · Cost: edit · operationId set-member-mix

For a group: when one member starts and how loud it is.

Parameters

Body

SetMemberMix.

Answers

Remove a character

POST /api/v1/projects/{project}/commands/remove-character

Needs the editor role · Cost: edit · operationId remove-character

Remove the character id from the cast; the narrator reads its lines. A member of a group can't be removed.

Parameters

Body

RemoveCharacter.

Answers

Give one character's lines to another and remove it

POST /api/v1/projects/{project}/commands/merge-character

Needs the owner role · Cost: edit · operationId merge-character

Give one character's lines to another and remove it.

Parameters

Body

CharacterMerge.

Answers

Pick the take a character's voice is made from

POST /api/v1/projects/{project}/commands/use-voice

Needs the editor role · Cost: edit · operationId use-voice

Use one of a character's voice takes, or with take None, the voice designed from its description again.

Parameters

Body

VoicePick.

Answers

Discard voice takes of a character

POST /api/v1/projects/{project}/commands/discard-takes

Needs the editor role · Cost: edit · operationId discard-takes

Delete some of a character's voice takes, none of them in use.

Parameters

Body

DiscardTakes.

Answers

Record a character's voice to make it from

POST /api/v1/projects/{project}/commands/record-voice

Needs the editor role · Cost: run-costly · Starts a takes job · operationId record-voice

A recording of a character's voice, to make a voice take from.

Parameters

Body

VoiceRecording.

Answers

Ask for takes of a group's first lines, to hear it

POST /api/v1/projects/{project}/commands/preview-group

Needs the editor role · Cost: run-costly · Starts a takes job · operationId preview-group

Ask for a take of each of the group id's first lines, read by its members at once, to hear it; a line with takes waiting is left as it is.

Parameters

Body

PreviewGroup.

Answers

Mark the drafted cast as looked at and right

POST /api/v1/projects/{project}/commands/mark-cast-reviewed

Needs the editor role · Cost: edit · operationId mark-cast-reviewed

The creator has looked at the drafted cast and marks it right.

Parameters

Body

CastReviewed.

Answers

Say who reads a line

POST /api/v1/projects/{project}/commands/set-speaker

Needs the editor role · Cost: edit · operationId set-speaker

Who says a line; null gives it to the narrator.

Parameters

Body

SetSpeaker.

Answers

Set what the voice says for a line

POST /api/v1/projects/{project}/commands/set-say

Needs the editor role · Cost: edit · operationId set-say

What the voice says for a line, in place of the book's words; null says the book's words again.

Parameters

Body

SetSay.

Answers

Set how a line is said, in words

POST /api/v1/projects/{project}/commands/set-how

Needs the editor role · Cost: edit · operationId set-how

How a line is said, in words ("whisper it, scared"); null takes that away.

Parameters

Body

SetHow.

Answers

Play a sound in place of a line's words

POST /api/v1/projects/{project}/commands/set-sound

Needs the editor role · Cost: edit · operationId set-sound

A sound that plays in place of a line's words; null takes it away.

Parameters

Body

SetSound.

Answers

Pick the take a line plays

POST /api/v1/projects/{project}/commands/pick-take

Needs the editor role · Cost: edit · operationId pick-take

The take a line plays; null goes back to the take the build reads.

Parameters

Body

PickTake.

Answers

Mark a line to come back to, or take the mark away

POST /api/v1/projects/{project}/commands/mark-line

Needs the editor role · Cost: edit · operationId mark-line

Mark a line to come back to, or take the mark away.

Parameters

Body

LineMark.

Answers

Trim the start and end of the clip a line plays

POST /api/v1/projects/{project}/commands/trim-clip

Needs the editor role · Cost: edit · operationId trim-clip

Cut start_ms from the start and end_ms from the end of the clip a line plays, or with both 0, take its trim away (trimming clips, TM2).

Parameters

Body

TrimAsk.

Answers

Shape a clip's loudness over time

POST /api/v1/projects/{project}/commands/set-envelope

Needs the editor role · Cost: edit · operationId set-envelope

Make the clip a line plays as loud over its length as points say, (ms into the clip, dB) in order, or with none, take its envelope away (volume-envelope.md, VE2).

Parameters

Body

EnvelopeAsk.

Answers

Set the silence after a line

POST /api/v1/projects/{project}/commands/set-pause

Needs the editor role · Cost: edit · operationId set-pause

Make the silence after a line's words ms long, in place of the build's own gap there, or with None, the build's own again (pauses.md, PA1).

Parameters

Body

PauseAsk.

Answers

Cut the clip a line plays in two

POST /api/v1/projects/{project}/commands/cut-clip

Needs the editor role · Cost: edit · operationId cut-clip

Cut the clip a line plays in two (cutting-clips.md, CT2): its audio at ms into the clip, its words before the word starting at at (a code point of its sentence) and from it on.

Parameters

Body

CutAsk.

Answers

Use another line's reading of the same words

POST /api/v1/projects/{project}/commands/borrow-reading

Needs the editor role · Cost: edit · operationId borrow-reading

Borrow another line's reading of the same words for the line key (borrowed-takes.md, BT4): source as lines/{key}/borrow-sources named it.

Parameters

Body

BorrowAsk.

Answers

Record a line in your own voice

POST /api/v1/projects/{project}/commands/record-line

Needs the editor role · Cost: edit · operationId record-line

One line read aloud on the Timeline, cut and made mono in the page, its WAV sent as base64, to keep as a take of the line (recording-voices.md, RV5, RV6).

Parameters

Body

LineRecording.

Answers

Record how a line should be said, for its direction

POST /api/v1/projects/{project}/commands/record-how

Needs the editor role · Cost: run-costly · Starts a takes job · operationId record-how

A line read aloud in the Fix sheet to show how it goes, made mono in the page, its WAV sent as base64 (delivery-from-recording.md, DR1, DR2).

Parameters

Body

HowRecording.

Answers

Forget a recording of how to say a line

POST /api/v1/projects/{project}/commands/forget-how

Needs the editor role · Cost: edit · operationId forget-how

The creator's reading of a line, to forget.

Parameters

Body

HowReadingRef.

Answers

Discard takes of lines

POST /api/v1/projects/{project}/commands/discard-line-takes

Needs the editor role · Cost: edit · operationId discard-line-takes

Delete some takes of lines, none of them in use.

Parameters

Body

DiscardLineTakes.

Answers

Read a sentence in one go with the next, or apart

POST /api/v1/projects/{project}/commands/join-sentences

Needs the editor role · Cost: edit · operationId join-sentences

Read a sentence in one go with the one before it (True), apart from it (False), or as the build decides (None).

Parameters

Body

JoinAsk.

Answers

Mark a sentence's words as spoken or not

POST /api/v1/projects/{project}/commands/set-spoken

Needs the editor role · Cost: edit · operationId set-spoken

Read a sentence aloud (True), or show it and don't read it (False).

Parameters

Body

SpokenAsk.

Answers

Give some of a sentence's words to a reader

POST /api/v1/projects/{project}/commands/give-words

Needs the editor role · Cost: edit · operationId give-words

Give some words of a sentence to the narrator (narrator) or a character (SF14, splitting lines SL1): a stretch of one segment, in code points, as the Fix sheet picks it or the Lines screen splits a line there.

Parameters

Body

GiveWords.

Answers

Put a sentence's lines back as they were (an undo)

POST /api/v1/projects/{project}/commands/restore-lines

Needs the editor role · Cost: edit · operationId restore-lines

Put a sentence's lines back as they were, with the takes of other lines a split set aside picked again: the Undo of a split or of putting lines together. Its clips' volumes and clean-ups, when given, are put back as they were too (readings.md, RD9).

Parameters

Body

RestoreLines.

Answers

Play a sound in place of some of a sentence's words

POST /api/v1/projects/{project}/commands/set-words-sound

Needs the editor role · Cost: edit · operationId set-words-sound

Play a sound in place of some words of the book: a stretch of one segment, in code points.

Parameters

Body

WordsAsSound.

Answers

Set how one clip is cleaned of noise

POST /api/v1/projects/{project}/commands/set-clip-cleanup

Needs the editor role · Cost: edit · operationId set-clip-cleanup

Clean one clip of noise its own way, or as the whole book does (null).

Parameters

Body

SetClipCleanup.

Answers

Set how the whole book is cleaned of noise

POST /api/v1/projects/{project}/commands/set-book-cleanup

Needs the owner role · Cost: edit · operationId set-book-cleanup

How every clip of the book is cleaned of noise, unless it has its own way.

Parameters

Body

SetBookCleanup.

Answers

Set how loud a clip plays

POST /api/v1/projects/{project}/commands/set-volume

Needs the editor role · Cost: edit · operationId set-volume

Make a clip louder or quieter, in dB; 0 leaves it as read (clip-volume.md, VL4). The studio makes every other piece of the reading in one go it is a piece of as loud (readings.md, RD4).

Parameters

Body

VolumeAsk.

Answers

Set the model every voice of the book is cleaned with

POST /api/v1/projects/{project}/commands/set-book-cleanup-model

Needs the owner role · Cost: edit · operationId set-book-cleanup-model

The model every voice of the book is cleaned with, unless a voice, a take or a clip has its own (cleanup-models.md, CM15).

Parameters

Body

SetBookCleanupModel.

Answers

Set the model a character's voice, or the narrator's, is cleaned with

POST /api/v1/projects/{project}/commands/set-voice-cleanup-model

Needs the editor role · Cost: edit · operationId set-voice-cleanup-model

The model a character's voice, or the narrator's (narrator), is cleaned with, or as the whole book (null).

Parameters

Body

SetVoiceCleanupModel.

Answers

Set the model a take is cleaned with

POST /api/v1/projects/{project}/commands/set-take-cleanup-model

Needs the editor role · Cost: edit · operationId set-take-cleanup-model

The model a take is cleaned with, or as its voice (null).

Parameters

Body

SetTakeCleanupModel.

Answers

Set the model one clip is cleaned with

POST /api/v1/projects/{project}/commands/set-clip-cleanup-model

Needs the editor role · Cost: edit · operationId set-clip-cleanup-model

The model one clip is cleaned with, or as its take or voice (null).

Parameters

Body

SetClipCleanupModel.

Answers

Put clean-up models back as they were (an undo)

POST /api/v1/projects/{project}/commands/restore-cleanup-models

Needs the editor role · Cost: edit · operationId restore-cleanup-models

Put clean-up models back as they were: the whole book's, when given, and each voice's, take's and clip's named, null for none of its own. The Undo of setting one.

Parameters

Body

RestoreCleanupModels.

Answers

Ask for takes of a line

POST /api/v1/projects/{project}/commands/queue-line-takes

Needs the editor role · Cost: run-costly · Starts a takes job · operationId queue-line-takes

Ask for takes of a line, made by the next takes job.

Parameters

Body

QueueLineTakes.

Answers

Ask for voice takes of a character

POST /api/v1/projects/{project}/commands/queue-voice-takes

Needs the editor role · Cost: run-costly · Starts a takes job · operationId queue-voice-takes

Ask for voice takes of a character, to pick its voice from.

Parameters

Body

QueueVoiceTakes.

Answers

Ask for takes of one run of a sentence, made next

POST /api/v1/projects/{project}/commands/queue-sentence-takes

Needs the editor role · Cost: run-costly · Starts a takes job · operationId queue-sentence-takes

Takes of one run of a sentence, made now or right after the running job, from the reader's Fix sheet (sentence fixes, SF4).

Parameters

Body

SentenceTakesAsk.

Answers

Ask for voice takes of every character with no voice yet

POST /api/v1/projects/{project}/commands/queue-everyone

Needs the editor role · Cost: run-costly · Starts a takes job · operationId queue-everyone

Voice takes for every character with no voice picked and none to hear.

Parameters

Body

EveryoneAsk.

Answers

Take back takes asked for and not made yet

POST /api/v1/projects/{project}/commands/unqueue

Needs the editor role · Cost: edit · operationId unqueue

Take back the request id for takes, asked for and not made yet.

Parameters

Body

QueuedRef.

Answers

Say how a word is said, everywhere in the book

POST /api/v1/projects/{project}/commands/respell

Needs the editor role · Cost: edit · operationId respell

Say word as respelling from now on.

Parameters

Body

Respell.

Answers

Take a word's respelling away

POST /api/v1/projects/{project}/commands/unrespell

Needs the editor role · Cost: edit · operationId unrespell

Take the respelling of word away, so it is said as written; a suggested one is never suggested again.

Parameters

Body

Unrespell.

Answers

Keep a suggested respelling of a word

POST /api/v1/projects/{project}/commands/keep-respelling

Needs the editor role · Cost: edit · operationId keep-respelling

Keep the respelling suggested for word as the creator's own.

Parameters

Body

KeepRespelling.

Answers

Ask for takes of a word as respelled

POST /api/v1/projects/{project}/commands/word-takes

Needs the editor role · Cost: run-costly · Starts a takes job · operationId word-takes

Takes of word said as respelling, to hear before it is saved.

Parameters

Body

WordTakesAsk.

Answers

Add a sound to the project

POST /api/v1/projects/{project}/commands/add-sound

Needs the editor role · Cost: edit · operationId add-sound

A recorded sound with its rights, its WAV sent as base64: the file the creator picked, in whatever format, converted in the page, with that file's name and SHA-256.

Parameters

Body

NewSound.

Answers

Remove a sound from the project

POST /api/v1/projects/{project}/commands/remove-sound

Needs the editor role · Cost: edit · operationId remove-sound

A sound in the studio's list, by its name relative to the cast file.

Parameters

Body

SoundRef.

Answers

Add a background under some sentences

POST /api/v1/projects/{project}/commands/add-background

Needs the editor role · Cost: edit · operationId add-background

Add a background under some sentences.

Parameters

Body

AddBackground.

Answers

Set everything about a background

POST /api/v1/projects/{project}/commands/set-background

Needs the editor role · Cost: edit · operationId set-background

Set everything about a background that is there already.

Parameters

Body

SetBackground.

Answers

Remove a background

POST /api/v1/projects/{project}/commands/remove-background

Needs the editor role · Cost: edit · operationId remove-background

Remove the background id from under its sentences.

Parameters

Body

BackgroundRef.

Answers

Pick the voice engine the book is read with

POST /api/v1/projects/{project}/commands/set-engine

Needs the owner role · Cost: edit · operationId set-engine

The voice engine the book is read with.

Parameters

Body

SetEngine.

Answers

Pick the engine's voice the narrator reads with

POST /api/v1/projects/{project}/commands/set-narrator-name

Needs the editor role · Cost: edit · operationId set-narrator-name

The engine's voice the narrator reads with, by its name.

Parameters

Body

SetNarratorName.

Answers

Say how the narrator should sound

POST /api/v1/projects/{project}/commands/set-narrator-description

Needs the editor role · Cost: edit · operationId set-narrator-description

How the narrator should sound, for designing its voice.

Parameters

Body

SetNarratorDescription.

Answers

Go back to a narrator voice designed from its description

POST /api/v1/projects/{project}/commands/use-designed-narrator

Needs the editor role · Cost: edit · operationId use-designed-narrator

Go back to a narrator voice designed from its description, from a recording.

Parameters

Body

UseDesignedNarrator.

Answers

Record the narrator's voice to make it from

POST /api/v1/projects/{project}/commands/set-narrator-clip

Needs the editor role · Cost: edit · operationId set-narrator-clip

A recording of the narrator's voice to clone.

Parameters

Body

NarratorClip.

Answers

Set the seed readings are made with

POST /api/v1/projects/{project}/commands/set-seed

Needs the editor role · Cost: edit · operationId set-seed

The seed readings are made with, so a build can be made again the same.

Parameters

Body

SetSeed.

Answers

Pick which of Breeze's loops reads

POST /api/v1/projects/{project}/commands/set-breeze-loop

Needs the editor role · Cost: edit · operationId set-breeze-loop

Which of Breeze's loops reads: its own, or the faster one.

Parameters

Body

SetBreezeLoop.

Answers