This page explains how programmers can pull dialogue and VO data from Frostune:VO for use in custom engines, proprietary pipelines, Wwise/FMOD helpers, build tools, automation scripts, or internal production tools.
The integration manifest is a JSON payload using the schema:
frostune.integration.v1
It exposes dialogue line metadata, speaker data, scene data, filenames, production status, optional text/notes, optional custom properties, and optional Wwise-style path helpers.
The FTVO Integration Manifest can be accessed in two main ways:
| Method | Use Case |
|---|---|
| Live API | Pull data directly from the currently open FTVO project |
| Manual Export | Export a JSON file from FTVO and use it offline |
Both methods use the same frostune.integration.v1 schema and item structure.
Some
metafields may differ slightly between Live API and Manual Export.
The Live API allows an external tool to query the currently open Frostune:VO project.
Default local endpoint:
http://localhost:5000/api/integration/manifest
Example:
curl "http://localhost:5000/api/integration/manifest"
This returns a JSON manifest for the currently loaded FTVO project.
Frostune:VO is designed primarily for local workflows.
When called from the same machine as Frostune:VO, the Live API can be accessed directly:
http://localhost:5000/api/integration/manifest
Localhost access does not require a license header or agent token.
For LAN, VPN, or remote access, clients should use the Agent Read Token:
curl -H "X-FTVO-Agent-Token: YOUR_AGENT_READ_TOKEN" \
"http://YOUR_FTVO_MACHINE_IP:5000/api/integration/manifest?includeText=1"
A licensed automation tool may also use a license bearer token:
curl -H "Authorization: Bearer YOUR_LICENSE_TOKEN" \
"http://localhost:5000/api/integration/manifest?includeText=1"
For most production workflows, keep access limited to localhost, VPN, or trusted LAN/internal production networks.
The Live API supports query parameters for controlling how much data is returned.
Example:
curl "http://localhost:5000/api/integration/manifest?includeText=1&includeNotes=1&includeHasWav=1&includeCustomProps=1"
| Parameter | Values | Default | Description |
|---|---|---|---|
includeText |
1, true, yes |
false |
Include dialogue text |
includeNotes |
1, true, yes, 0, false, no |
true |
Include line notes |
includeHasWav |
1, true, yes |
false |
Check whether the WAV exists on disk |
includeCustomProps |
1, true, yes |
false |
Include custom property definitions and values |
voicesRoot |
path | current FTVO VO output folder | Override the folder used for WAV existence checks |
eventTemplate |
string template | Play_{key} |
Customize generated event names |
originalsSubFolderTemplate |
string template | VO\{sceneTag}\{speakerSlug} |
Customize Wwise originals subfolder |
objectPathTemplate |
string template | VO\{sceneTag}\{key}_{speakerSlug} |
Customize Wwise object path |
FTVO can also export the same integration data as a JSON file.
This is useful when:
The exported file uses:
frostune.integration.v1
and contains an items array with the same main line structure as the Live API.
A typical response looks like this:
{
"meta": {
"schema": "frostune.integration.v1",
"exportedAt": "2026-05-08T00:39:16.905Z",
"projectName": "NewMay2026",
"voicesRoot": "C:\\Users\\Admin\\AppData\\Roaming\\FrostuneVO\\VO\\EN",
"options": {
"includeText": false,
"includeNotes": true,
"includeHasWav": false,
"includeCustomProps": false
}
},
"items": [
{
"id": "3471d6cc-bbae-484e-b15e-ea6b99041d24",
"stringId": "New_Folder_SCENE_2_ADAM@VO_3471d6.wav",
"sceneId": "3fc9bbd8-80f8-46ac-995a-8acc3bc7821f",
"sceneTag": "SCENE_2",
"sceneName": "Scene_2",
"sceneFolder": "New_Folder",
"index": 2,
"speaker": "Adam",
"speakerTag": "ADAM",
"speakerGender": "",
"filename": "VO_3471d6.wav",
"key": "VO_3471d6",
"wavRel": "VO_3471d6.wav",
"hasWav": null,
"spatialMode": "3d",
"priority": 50,
"delaySeconds": 0,
"status": {
"lineStatus": "to-record",
"wavStatus": "tts",
"flags": {}
},
"wwise": {
"eventName": "Play_VO_3471d6",
"originalsSubFolder": "VO\\SCENE_2\\adam",
"objectPath": "VO\\SCENE_2\\VO_3471d6_adam"
},
"text": null,
"notes": "",
"custom": null
}
]
}
metaThe meta object describes the manifest.
| Field | Type | Description |
|---|---|---|
schema |
string | Manifest schema version. Current value: frostune.integration.v1 |
exportedAt |
string | ISO timestamp when the manifest was generated |
projectName |
string | FTVO project name |
voicesRoot |
string | Base folder used for voice/WAV output |
pattern |
string | Filename pattern, when available |
counts |
object | Count summary, when available |
options |
object | Options used to generate the manifest |
customProps |
object | Custom property definitions, when includeCustomProps=1 |
Live API and Manual Export may not include exactly the same
metasubfields, but they share the same schema and item structure.
items[]Each entry in items represents one dialogue line with a WAV filename.
Scene-action-only rows are not included if they do not have an associated WAV filename.
| Field | Type | Description |
|---|---|---|
id |
string | FTVO line ID |
stringId |
string | Stable string/audio identifier generated from folder, scene, speaker, and WAV name |
sceneId |
string | FTVO scene ID |
sceneTag |
string | Stable scene tag |
sceneName |
string | Human-readable scene name |
sceneFolder |
string | FTVO folder path |
index |
number/null | Line index inside the scene |
speaker |
string | Character/speaker name |
speakerTag |
string | Stable character/speaker tag |
speakerGender |
string | Speaker gender metadata, when available |
filename |
string | WAV filename |
key |
string | WAV filename without .wav |
wavRel |
string | Relative WAV path |
hasWav |
boolean/null | true/false when includeHasWav=1, otherwise null |
spatialMode |
string | 2d or 3d |
priority |
number | Runtime VO priority |
delaySeconds |
number | Delay before playback |
status |
object | FTVO production status data |
wwise |
object | Wwise-style event/path helper data |
text |
string/null | Dialogue text when includeText=1, otherwise null |
notes |
string/null | Notes when included |
custom |
object/null | Custom property values when includeCustomProps=1, otherwise null |
statusThe status object contains FTVO production status data for each line.
Example:
"status": {
"lineStatus": "to-record",
"wavStatus": "tts",
"flags": {}
}
| Field | Type | Notes |
|---|---|---|
lineStatus |
string | FTVO line status, such as none, to-record, to-retake, out-for-recording, recorded, etc. |
wavStatus |
string | FTVO WAV/audio status, such as none, tts, temporary, final, waiting-temp-recorded, waiting-final-recorded, etc. |
flags |
object | Reserved for future status flags |
This is useful for build tools and custom engines that need to know whether a line is final, temporary, generated by TTS, ready for recording, or waiting for final audio.
wwiseThe wwise object contains helper paths for Wwise-style or event-based pipelines.
Example:
"wwise": {
"eventName": "Play_VO_3471d6",
"originalsSubFolder": "VO\\SCENE_2\\adam",
"objectPath": "VO\\SCENE_2\\VO_3471d6_adam"
}
| Field | Type | Description |
|---|---|---|
eventName |
string | Suggested event name |
originalsSubFolder |
string | Suggested Wwise Originals subfolder |
objectPath |
string | Suggested Wwise object path |
These fields are generated from templates.
Default templates:
eventTemplate = Play_{key}
originalsSubFolderTemplate = VO\{sceneTag}\{speakerSlug}
objectPathTemplate = VO\{sceneTag}\{key}_{speakerSlug}
The integration manifest supports template replacement for Wwise helper fields.
Available variables:
| Variable | Description |
|---|---|
{key} |
WAV filename without .wav |
{filename} |
Full WAV filename |
{sceneTag} |
Scene tag |
{sceneName} |
Scene name |
{sceneFolder} |
FTVO folder path |
{speaker} |
Speaker name |
{speakerTag} |
Speaker tag |
{speakerSlug} |
Lowercase/safe speaker slug |
{stringId} |
FTVO string ID |
Example:
curl "http://localhost:5000/api/integration/manifest?eventTemplate=VO_{sceneTag}_{speakerTag}_{key}"
By default, includeText is disabled for the Live API.
This keeps the response lighter and avoids exposing script text unless specifically requested.
To include text:
curl "http://localhost:5000/api/integration/manifest?includeText=1"
Then each item will include:
"text": "The dialogue line text."
Without includeText=1, the field is still present but returns:
"text": null
Notes are enabled by default in the Live API.
To explicitly include notes:
curl "http://localhost:5000/api/integration/manifest?includeNotes=1"
To disable notes:
curl "http://localhost:5000/api/integration/manifest?includeNotes=0"
To check whether WAV files exist on disk:
curl "http://localhost:5000/api/integration/manifest?includeHasWav=1"
When enabled, each item includes:
"hasWav": true
or:
"hasWav": false
When disabled, hasWav is:
"hasWav": null
You can override the WAV root with:
curl "http://localhost:5000/api/integration/manifest?includeHasWav=1&voicesRoot=D:\Project\VO\EN"
If the project uses FTVO Custom Properties, they can be included with:
curl "http://localhost:5000/api/integration/manifest?includeCustomProps=1"
The manifest will include property definitions in:
"meta": {
"customProps": {
"defs": []
}
}
Each line item will include:
"custom": {}
or:
"custom": null
depending on whether custom properties are enabled.
A custom engine integration usually follows this pattern:
items[].filename / wavRel to resolve audio files.sceneTag, sceneFolder, speakerTag, and stringId for organization.status.lineStatus and status.wavStatus to decide whether the line is usable.priority, spatialMode, and delaySeconds for runtime playback logic.async function getFtvoManifest() {
const res = await fetch(
"http://localhost:5000/api/integration/manifest?includeText=1&includeNotes=1"
);
if (!res.ok) {
throw new Error(`FTVO manifest failed: ${res.status}`);
}
return await res.json();
}
getFtvoManifest().then((manifest) => {
console.log(manifest.meta.schema);
console.log(manifest.items.length);
for (const line of manifest.items) {
console.log(line.sceneTag, line.speakerTag, line.filename, line.status);
}
});
import requests
url = "http://localhost:5000/api/integration/manifest"
params = {
"includeText": "1",
"includeNotes": "1",
"includeHasWav": "1",
}
r = requests.get(url, params=params)
r.raise_for_status()
manifest = r.json()
print(manifest["meta"]["schema"])
print(len(manifest["items"]))
for item in manifest["items"]:
print(
item["sceneTag"],
item["speakerTag"],
item["filename"],
item["status"]["lineStatus"],
item["status"]["wavStatus"],
)
import requests
url = "http://192.168.1.50:5000/api/integration/manifest"
headers = {
"X-FTVO-Agent-Token": "YOUR_AGENT_READ_TOKEN"
}
params = {
"includeText": "1",
"includeNotes": "1"
}
r = requests.get(url, headers=headers, params=params)
r.raise_for_status()
manifest = r.json()
print(manifest["meta"]["projectName"])
id as the primary line identity.stringId when you need a production-friendly string/audio identifier.sceneTag and speakerTag stable.status.wavStatus to decide whether a line has usable/generated/final audio.status.lineStatus to understand recording/script status.includeText=1 only when the external tool needs script text.includeHasWav=1 only when the external tool needs disk validation.X-FTVO-Agent-Token for non-local access.| Need | Recommended Approach |
|---|---|
| Pull current FTVO data locally | GET /api/integration/manifest |
| Pull over LAN/VPN | Use X-FTVO-Agent-Token |
| Include dialogue text | Add ?includeText=1 |
| Include notes | Add ?includeNotes=1 |
| Check WAV existence | Add ?includeHasWav=1 |
| Include Custom Properties | Add ?includeCustomProps=1 |
| Generate Wwise helper names | Use wwise object |
| Build custom runtime playback | Use filename, status, priority, spatialMode, and delaySeconds |
| Freeze data for build/release | Use Manual Export |