screenplay_writing_voice
Inspect transparent presets, select, author, analyze, and explicitly save the project-scoped Screenplay Writing Voice used for screenplay page expression.
When to use
Use `operation=get` to inspect the active selection and preset summaries, and `preset_get` for one complete preset plus its exact Writer Instructions.
Use `operation=select` to persist one visible preset or the exact saved Custom revision as the project selection.
Use `operation=save` to create or replace the complete compact Voice with an exact expected revision.
Use `analysis_readiness`, `analysis_start`, and `analysis_finalize` with `analysis_mode=design` for two alternatives or `analysis_mode=infer` for one sample-faithful proposal.
After saving, pass `{kind: custom, revision: N}` to `screenplay_generation_run` to use that exact revision.
When not to use
Do not use for Novel Adaptation Voice Lab; use `story_development_run(workflow=novel_adaptation)`.
Do not use for character or narrator audio references; use `voice_profile`.
Do not use for `tv_season`, which plans a season but does not write screenplay pages.
Analysis never saves. Saving Custom Voice explicitly activates its new revision.
Examples
“Read the current Writing Voice status for project 123.”
“Analyze these two screenplay samples, review the proposal, then save my edits at its expected revision.”
“Save this compact Voice contract at expected revision 0.”
Anti-examples
- Clone a Novel Voice profile into a screenplay project.
- Create a speech reference sample for a character.
Backend capabilities
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"operation",
"project_id"
],
"properties": {
"operation": {
"type": "string",
"enum": [
"get",
"preset_get",
"select",
"save",
"analysis_readiness",
"analysis_start",
"analysis_finalize"
]
},
"project_id": {
"type": "integer"
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"if_match_updated_at": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"preset_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"selection": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"preset_id"
],
"properties": {
"kind": {
"const": "preset"
},
"preset_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"revision"
],
"properties": {
"kind": {
"const": "custom"
},
"revision": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}
]
},
"voice": {
"type": "object",
"required": [
"schema_version",
"label",
"action_style",
"dialogue_style",
"page_rhythm"
],
"properties": {
"schema_version": {
"const": 1
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"action_style": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"dialogue_style": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"page_rhythm": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"tone_and_atmosphere": {
"type": "string",
"maxLength": 4000
},
"voice_boundaries": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 8,
"uniqueItems": true
},
"samples": {
"type": "array",
"maxItems": 3,
"items": {
"type": "object",
"required": [
"sample_id",
"label",
"excerpt"
],
"properties": {
"sample_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"excerpt": {
"type": "string",
"minLength": 1,
"maxLength": 30000
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"description": {
"type": "string",
"maxLength": 12000
},
"analysis_mode": {
"type": "string",
"enum": [
"design",
"infer"
]
},
"samples": {
"type": "array",
"maxItems": 3,
"items": {
"type": "object",
"required": [
"sample_id",
"label",
"excerpt"
],
"properties": {
"sample_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"excerpt": {
"type": "string",
"minLength": 1,
"maxLength": 30000
}
},
"additionalProperties": false
}
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"job_id": {
"type": "string",
"minLength": 1
}
},
"allOf": [
{
"if": {
"properties": {
"operation": {
"const": "preset_get"
}
}
},
"then": {
"required": [
"preset_id"
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "select"
}
}
},
"then": {
"required": [
"selection"
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "save"
}
}
},
"then": {
"required": [
"expected_revision",
"voice"
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "analysis_start"
}
}
},
"then": {
"required": [
"idempotency_key",
"analysis_mode"
],
"allOf": [
{
"if": {
"properties": {
"analysis_mode": {
"const": "design"
}
}
},
"then": {
"required": [
"description"
],
"properties": {
"description": {
"minLength": 1,
"pattern": "\\S"
}
}
}
},
{
"if": {
"properties": {
"analysis_mode": {
"const": "infer"
}
}
},
"then": {
"required": [
"samples"
],
"properties": {
"samples": {
"minItems": 1
}
}
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "analysis_finalize"
}
}
},
"then": {
"required": [
"job_id"
]
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"operation",
"project_id",
"writing_voice_updated_at"
],
"properties": {
"operation": {
"type": "string",
"enum": [
"get",
"preset_get",
"select",
"save",
"analysis_readiness",
"analysis_start",
"analysis_finalize"
]
},
"project_id": {
"type": "integer"
},
"mode": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"minimum": 0
},
"writing_voice_updated_at": {
"type": [
"string",
"null"
]
},
"exists": {
"type": "boolean"
},
"label": {
"type": [
"string",
"null"
]
},
"sample_count": {
"type": "integer",
"minimum": 0,
"maximum": 3
},
"selection": {
"type": "object",
"additionalProperties": true
},
"preset_summaries": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"preset": {
"type": "object",
"additionalProperties": true
},
"async": {
"type": "boolean"
},
"job_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
},
"readiness": {
"type": "object",
"additionalProperties": true
},
"proposal_summaries": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"estimated_credits": {
"type": "integer",
"minimum": 0
},
"credits_charged": {
"type": "integer",
"minimum": 0
},
"credits_skipped_reason": {
"type": "string"
},
"resource_links": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"next_actions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": true
}