Smart Oral Cut

One-click smart editing for talking-head raw footage, producing results on par with a human rough cut:

• Retake & misread removal: when the same content is recorded multiple times, only the last fluent take is kept; misreads, slips and abandoned half-sentences are removed (with intra-sentence precision);
• Breath cleanup: overlong intra-sentence pauses and breath sounds are tightened automatically;
• Rhythm shaping: pause length follows script punctuation (comma / period / question mark / paragraph each adjustable), and cut points snap to the quietest audio frames to avoid popping artifacts.

Two modes are supported: providing the script (script) aligns the footage against it word by word for the best quality; without a script, the intended final script is reconstructed by smart analysis.

Mix and match outputs (outputs): project files (the .xml for Premiere by default; in project_formats you can also pick Jianying / CapCut / FCPX / OTIO / Tonghe .gtrk to keep refining in the matching editor), edit report (what was cut and why), and rendered video (mp4). In addition, every task always includes a transcript file (transcript.json, source-timebase word-level timecodes covering all recognized content) with no toggle required — for downstream splitting / timeline-placement consumers.

Among these, .gtrk is the Tonghe unified editing contract (gtrk v1): add gtrk to project_formats and it is produced as one of the project files in files[] (alongside xml / Jianying / etc.). It can be imported into the Tonghe client for further refinement, or fed back as-is to Project File Export to convert to other NLE projects, or to Timeline Render for cloud rendering — the same edit structure throughout, with no re-parsing.

Create Task

Basics

Item	Value
Method	POST
Path	/task/video_oral_cut
Content-Type	application/json
Auth	Authorization header (raw API Key)
Billing	by input video duration (minutes)

Request Body

Name	Type	Required	Default	Description
file_id	string	Yes	—	File ID of the raw talking-head video (via File Upload)
script	string	No	—	Original script (with punctuation and line breaks; 10–50000 chars excluding whitespace). Strongly recommended: script mode aligns word by word and yields the best quality. Omit to use smart reconstruction
la	string	No	zh-CN	Language. Chinese is the primary target; other languages are best-effort
outputs	array	No	["project"]	Output selection, any combination of project / video. project = produce project files per project_formats (only Premiere's .xml by default); video = render the cut. Which project formats are produced (including gtrk) is decided by project_formats, not specified in outputs
project_formats	array	No	["xml"]	Effective when outputs contains project; specifies which project formats to produce (multiple allowed): xml (Premiere Pro) / fcpxml (Final Cut Pro) / otio (OpenTimelineIO) / jianying (Jianying) / capcut (CapCut) / gtrk (Tonghe .gtrk, openable directly in the client). Only xml is produced by default; list gtrk or other formats explicitly to get them
render	object	No	{}	Effective when outputs contains video, see table below
rhythm_preset	string	No	—	Rhythm preset: steady / concise / compact, see preset table below. Omit for the built-in default rhythm. A preset sets the baseline; the individual rhythm parameters below still override per key
adaptive_rhythm	boolean	No	true	Adaptive rhythm: learns the speaker's own pausing habits (how long they pause at each punctuation) and shapes pauses anchored to their natural cadence, while cleaning mid-phrase hesitation pauses — the result sounds like the speaker. false falls back to the fixed parameter tables
punctuation_breaks	object	No	see below	Punctuation → pause seconds map; provided keys override defaults/preset values (each 0–5 s)
intra_gap_max	number	No	0.35	Intra-sentence pauses longer than this (seconds) are treated as breath gaps and tightened (0–5)
intra_gap_target	number	No	0.10	Target length a breath gap is tightened to; must be less than intra_gap_max
pad_in	number	No	0.05	Lead-in margin at the head of each kept segment (seconds, 0–5)
pad_out	number	No	0.08	Tail margin at the end of each kept segment (seconds, 0–5)
visual_assist	boolean	No	false	Visual-assisted recovery: cross-checks speech recognition against on-screen speaking detection, protecting occasionally missed passages from being cut and attempting to recover the missed words. Increases processing time (runs in parallel with main recognition); no extra charge
source_path	string	⚠️ Conditional	—	Full local path of the raw footage in your editing environment (e.g. C:\clips\footage.mp4), written as-is into project file media references so editors recognize the media on import. Required when outputs contains project (the default outputs already includes project, so usually required); length ≤ 1024; the server neither validates its existence nor transforms it
struct_meta	object	No	{}	Same as Project File Export: contains nle_draft_dir (your local draft folder; the legacy name capcut_draft_path is still accepted as an alias). Without it, Jianying / CapCut draft meta files (*_meta) cannot be produced

render object

Field	Type	Default	Description
codec	string	h264	Video encoder; only h264 for now
crf	integer	18	Quality, 14 (high quality) – 28 (small size)
audio_crossfade_ms	integer	8	Audio fade at cut points in ms (0–50) to remove popping; 0 for hard cuts

rhythm_preset table (full parameter bundle per preset)

Parameter	steady	concise	compact	Default (omitted)
Best for	narration, teaching, demos	mid/long-form videos	short videos, ads	general
Style factor (adaptive mode: scales the speaker's own cadence)	×1.25	×1.0	×0.5	×1.0
、 / ， / ；	0.18 / 0.25 / 0.36	0.12 / 0.18 / 0.26	0.06 / 0.08 / 0.12	0.15 / 0.20 / 0.30
： / —	0.45 / 0.55	0.32 / 0.40	0.15 / 0.18	0.35 / 0.45
。 ！ / ？	0.55 / 0.60	0.40 / 0.45	0.18 / 0.20	0.45 / 0.50
…… / paragraph	0.75 / 1.20	0.55 / 0.90	0.25 / 0.40	0.60 / 1.00
intra_gap_max / intra_gap_target	0.45 / 0.15	0.35 / 0.10	0.25 / 0.05	0.35 / 0.10
pad_in / pad_out	0.05 / 0.10	0.05 / 0.08	0.03 / 0.05	0.05 / 0.08

punctuation_breaks defaults (baseline without a preset, i.e. the "Default" column above)

Punctuation	Default pause (s)	Punctuation	Default pause (s)
，	0.20	。	0.45
、	0.15	！	0.45
；	0.30	？	0.50
：	0.35	—	0.45
……	0.60	paragraph (line break in script)	1.00

💡 Rhythm tuning: pick the preset closest to your content type first, then fine-tune individual keys (e.g. rhythm_preset: "compact" + {"。": 0.3} relaxes only the period pause on a compact base). report.rhythm_preset echoes the preset actually used. Create multiple tasks on the same footage to compare pacing.

Request Example

curl -X POST https://api.ai-mcn.tv:10000/task/video_oral_cut \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "78246108192718854",
    "script": "Full script text with punctuation ...",
    "outputs": ["project", "video"],
    "project_formats": ["xml", "jianying", "gtrk"],
    "source_path": "C:\\clips\\footage.mp4",
    "struct_meta": {"nle_draft_dir": "C:\\Users\\Me\\AppData\\Local\\JianyingPro\\User Data\\Projects\\com.lveditor.draft\\20260611"},
    "render": {"crf": 18, "audio_crossfade_ms": 8},
    "punctuation_breaks": {"。": 0.4, "paragraph": 0.8}
  }'

Success Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178300",
    "task_type": "video_oral_cut",
    "status": "queued"
  }
}

---

Query Task Result

Basics

Item	Value
Method	GET
Path	/task/video_oral_cut/{task_id}
Auth	Authorization header (raw API Key)

Response (output_result)

Name	Type	Description
report	object	Edit report — what was cut and why (see below)
files	array	Artifact file list. When outputs includes project, project files are produced per project_formats (only ["xml"] by default), each with type=project; when it includes video, the rendered cut (type=video); in addition it always contains one transcript file (type=transcript, independent of outputs; best-effort: failures are recorded in errors.transcript and the task still completes)
errors	object	Per-artifact failure reasons (non-empty on partial success; keys like project / video)

.gtrk project file content (produced when project_formats includes gtrk)

Downloading the format=gtrk file in files[] yields a gtrk v1 unified editing contract that shares the data model with Project File Export / Timeline Render and can be fed back to either endpoint as-is or imported into the Tonghe client for re-editing: one video track + one audio track (same source, same cut points); each item in track_timeline is a kept speech segment. materials indexes media by id (file_id / path / duration / video_rate / video_size); path = the source_path input value as-is (recognized directly by editors; falls back to a filename placeholder when not provided).

report structure

Field	Type	Description
final_script	string	The final script actually used (script mode = your input; otherwise the reconstruction)
script_source	string	user / rebuilt
dropped	array	Removed segments, items {start, end, asr_text, reason}; reason: retake (superseded by a later take) / misread (slip, abandoned take, or off-script content)
uncovered_script	array	Script passages with no matching footage (likely skipped while recording); editing always follows the actual footage
review_points	array	Positions suggested for manual review, items {time, note}
insufficient_breaks	array	Positions where source footage lacked enough room for the configured pause, items {time, want, got}
rhythm_preset	string | null	The rhythm preset actually used; null when no preset
adaptive_rhythm	boolean	Whether adaptive rhythm actually took effect (falls back to fixed tables and false when the footage is too short for a reliable pause profile)
pause_profile	object	(adaptive only) The speaker's pause profile {class: {median, p75, n}} for tuning reference
analysis_degraded	boolean	true if smart analysis was temporarily unavailable and pure mechanical rules were used (task still completes)
suspect_omissions	array	(visual_assist=true only) Suspected missed-recognition intervals: {start, end, overlap, recovered}; overlap is the on-screen speaking overlap ratio, recovered indicates whether words were recovered
stt_recovered	array	(visual_assist=true only) Recovered words {start, end, text}, already merged into the edit result
visual_assist_degraded	boolean	(visual_assist=true only) true if on-screen detection was temporarily unavailable and the task proceeded as if disabled (task still completes)
coverage	number	Script coverage 0–1; below 0.6 an extra low_coverage: true flags a likely script/footage mismatch
duration_before	number	Duration before editing (seconds)
duration_after	number	Duration after editing (seconds)

files[] item

Field	Type	Description
type	string	project (project file) / video (rendered video) / transcript (transcript file, always produced)
format	string	Project: xml / fcpxml / otio / gtrk / jianying_draft / jianying_meta / capcut_draft / capcut_meta; video: mp4; transcript: json
file_id	string	Artifact file ID
download_url	string	Download path
filename	string	Suggested file name (draft files must keep this name inside the draft folder)
duration	number	(type=video only) rendered video duration in seconds

Success Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178300",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "report": {
        "final_script": "Full final script ...",
        "script_source": "user",
        "dropped": [
          {"start": 7.73, "end": 17.33, "asr_text": "first take ...", "reason": "retake"}
        ],
        "uncovered_script": [],
        "review_points": [],
        "insufficient_breaks": [],
        "analysis_degraded": false,
        "coverage": 0.982,
        "duration_before": 114.7,
        "duration_after": 68.59
      },
      "files": [
        {"type": "project", "format": "xml", "file_id": "537489015178300", "download_url": "/download/b0/537489015178300.xml", "filename": "premiere.xml"},
        {"type": "project", "format": "gtrk", "file_id": "537489015178301", "download_url": "/download/b1/537489015178301.gtrk", "filename": "project.gtrk"},
        {"type": "project", "format": "jianying_draft", "file_id": "537489015178302", "download_url": "/download/b2/537489015178302.json", "filename": "draft_content.json"},
        {"type": "video", "format": "mp4", "file_id": "537489015178303", "download_url": "/download/b3/537489015178303.mp4", "filename": "oral_cut.mp4", "duration": 68.59},
        {"type": "transcript", "format": "json", "file_id": "537489015178304", "download_url": "/download/b4/537489015178304.json", "filename": "transcript.json"}
      ],
      "errors": {}
    },
    "create_time": "2026-06-11T08:00:00Z",
    "update_time": "2026-06-11T08:03:10Z"
  }
}

Error Codes

Code	HTTP Status	Description	Solution
6013	400	file_id missing	Provide required parameters
6004	404	File not found	Check file_id
6014	400	File type mismatch (video file required)	Upload a video file
6016	400	Invalid business parameters (outputs / project_formats out of range, script length, rhythm parameters out of range, etc.; details in response)	Fix parameters as indicated
6502	401	Authentication failed	Check the Authorization header
6201	402	Insufficient quota	Purchase a quota package or top up
6202	402	Insufficient balance	Top up via dashboard

Limitations

• Single file, single camera: one raw clip per task; multi-camera editing is not supported yet.
• Script mode yields the best quality: Chinese is the primary target. Without a script, the reconstruction is best-effort and returned in report.final_script for verification.
• Billed by input duration: charged by raw footage length (minutes); choosing project / video outputs costs nothing extra.
• Core artifact guarantee: the task only fails (with automatic refund) if the edit analysis + report cannot be produced; project files, rendered video and the transcript file are all derived artifacts — a single failure is recorded in errors without failing the task.
• Transcript file (transcript.json): every task always produces a source-timebase, word-level-timecoded transcript covering all recognized content (including trimmed retakes / filler), for downstream splitting / timeline-placement consumers to project against the current project; it is a derived artifact (best-effort) — failures are recorded in errors.transcript without affecting task completion.
• Project media references: media paths inside drafts/projects come from your source_path input (written as-is); make sure it is the real location of the footage in your editing environment. To get fully openable Jianying / CapCut drafts, also provide struct_meta.nle_draft_dir.
• Editing follows the footage: the script is only an alignment reference; skipped passages are never fabricated and are listed in report.uncovered_script.
• Visual-assisted recovery (visual_assist): on-screen speaking detection protects suspected missed-recognition passages from being cut and attempts to recover the words; if recovery fails, the passage is kept as-is with a review_points note for manual review — content is never fabricated. Requires the speaker's face to be generally visible; adds processing time (parallel with main recognition, roughly the larger of the two); no extra charge.