Split

Fan one input into several outputs: pages out of a PDF, frames out of a GIF, or segments out of an audio or video file. One input, up to 200 outputs.

Input	How it splits	Availability
PDF	`page_range` (pick pages) or `page_groups` (N pages per output)	Stable
GIF	`frame_range` (pick frames)	Stable
Video (MP4, WebM, MOV)	`interval`, `count` or `cut_points`	Beta
Audio (MP3, AAC, OGG, FLAC, WAV, M4A)	`interval`, `count`, `cut_points`, or `silence` (beta)	Beta

The server picks the group from the input's media type, so the same call shape works for every input — only the options differ.

Always pass options

No input has a usable default split. Each group's default mode needs a key you must supply: page_range for a PDF (default mode page_range), interval for audio and video (default mode interval), and frame_range for a GIF. A split without it is refused by the server. TypeScript makes the options argument required; PHP defaults it to [], so a bare split() type-checks there and fails at the server. Pass the options for the input you have.

File-first

file(x).split({...}) returns a terminal recipe: you can chain steps before the split (convert('pdf') then split the PDF), but nothing after it, and a split recipe cannot go into batch([...]). It has only run() and submit().

TypeScript
PHP
Python
Rust

const result = await client
  .file('./report.pdf')
  .split({ mode: 'page_range', page_range: '1-3,7' })
  .run({ maxWait: '5m' });

for (const page of result.artifacts) {
  console.log(page.pageIndex, page.filename, page.url);
}
await result.downloadTo('./pages');

$result = $client->file('./report.pdf')
    ->split(['mode' => 'page_range', 'page_range' => '1-3,7'])
    ->run(maxWait: '5m');

foreach ($result->artifacts as $page) {
    echo $page->pageIndex, ' ', $page->filename, ' ', $page->url, "\n";
}
$result->downloadTo('./pages');

What `run()` returns

run() returns only the split's outputs. When steps run before the split, their intermediate file is consumed, not returned. Each output carries where it came from:

pageIndex (PDF): the 1-based source page. With page_range it is that page, so a sparse selection like '1,3,5' gives 1, 3, 5, not 1, 2, 3. With page_groups it is the group's first page.
position (GIF, audio, video): the 0-based ordinal of the frame or segment, when the server provides it. 0 is a real value. Do not rely on it being present.

result.url and toFile() are for exactly one output, so when a split yields more than one output they are empty and refuse (not_single_output) respectively. Iterate artifacts or call downloadTo(dir), which work for any number of outputs. A split that yields a single output (for example page_range: '3') has a url, and toFile() works.

submit() works as on any recipe: it returns a handle at once, and the handle's result() projects the same split outputs.

Single operation

client.split(x, {...}) is the one-step form. It takes the same options and returns the ordinary single-operation result.

TypeScript
PHP
Python
Rust

const result = await client
  .split('./talk.mp3', { mode: 'count', count: 4 })
  .run({ maxWait: '10m' });

for (const segment of result.artifacts) {
  console.log(segment.position, segment.filename);
}

use Gisl\Sdk\Ergonomic\RunOptions;

$result = $client->split('./talk.mp3', ['mode' => 'count', 'count' => 4])
    ->run(new RunOptions(maxWait: '10m'));

foreach ($result->artifacts as $segment) {
    echo $segment->position, ' ', $segment->filename, "\n";
}

Options

Twelve options in total. Each belongs to one or more groups. A key that is not one of the twelve is rejected locally, before the upload; one that belongs to a different group or mode than your input is refused by the server.

Option	Values	Default	Group
`frame_range`	`'start-end'`, 1-based inclusive (e.g. `'1-100'`)	none: required	GIF
`output_format`	`png` · `webp` · `jpg`	`png`	GIF
`mode`	PDF: `page_range` · `page_groups`. Audio and video: `interval` · `count` · `cut_points`. Audio only: `silence`	PDF: `page_range`. Audio and video: `interval`	PDF, audio, video
`page_range`	pages, e.g. `'1-5'` or `'1,3,5-7'` (1-based, inclusive)	required with `mode: 'page_range'`	PDF
`page_groups`	`2`–`200` pages per output	required with `mode: 'page_groups'`	PDF
`interval`	seconds, ≥ `0.001` (sub-second allowed)	required with `mode: 'interval'`	Audio, video
`count`	`2`–`200` equal-duration pieces	required with `mode: 'count'`	Audio, video
`cut_points`	a list of seconds, strictly increasing, each above `0` and below the duration (1–199 entries)	required with `mode: 'cut_points'`	Audio, video
`silence_threshold_db`	dBFS, ≤ `0`	`-50`	Audio, `mode: 'silence'`
`silence_min_duration`	seconds, ≥ `0.001`	`0.75`	Audio, `mode: 'silence'`
`silence_handling`	`keep_at_end`	`keep_at_end`	Audio, `mode: 'silence'`
`precision`	`fast` · `exact` (planned)	`fast`	Audio, video

Times are numeric seconds, not ISO 8601 durations, and cut_points is a list, not a comma-separated string.

PDF

mode: 'page_range' (the default) extracts the pages you list, one output per page. mode: 'page_groups' cuts the document into consecutive groups of N pages; the last group ends at the last page, so it may be shorter.

Video and audio

interval: a cut every N seconds. ceil(duration / interval) must be at most 200.
count: N equal-duration pieces.
cut_points: cut at the timestamps you give; the output count is cut_points.length + 1.

precision: 'fast' cuts at packet boundaries (audio: a few milliseconds of drift) or keyframes (video: typically up to 1–2 seconds). precision: 'exact' is planned: both SDKs refuse it before the upload with a GislConfigError whose reason is feature_not_available, so no bytes are sent for a split the API would refuse.

Audio silence mode (beta)

Audio only: mode: 'silence' cuts at detected silence gaps. A gap is audio below silence_threshold_db for at least silence_min_duration seconds; with silence_handling: 'keep_at_end' the trailing silence stays on the segment before the cut. More than 200 resulting segments is refused.

TypeScript
PHP
Python
Rust

const result = await client
  .file('./podcast.mp3')
  .split({ mode: 'silence', silence_threshold_db: -45, silence_min_duration: 1.5 })
  .run({ maxWait: '15m' });

$result = $client->file('./podcast.mp3')
    ->split(['mode' => 'silence', 'silence_threshold_db' => -45, 'silence_min_duration' => 1.5])
    ->run(maxWait: '15m');

GIF

frame_range is required: a 30-second GIF at 24 fps is 720 frames, past the 200-output cap, so there is no silent "every frame" default. Each frame comes back as output_format, at the source's dimensions.

TypeScript
PHP
Python
Rust

const frames = await client
  .file('./loop.gif')
  .split({ frame_range: '1-24', output_format: 'webp' })
  .run({ maxWait: '5m' });

$frames = $client->file('./loop.gif')
    ->split(['frame_range' => '1-24', 'output_format' => 'webp'])
    ->run(maxWait: '5m');

Split after another step

Steps before the split run in an upstream job, and the split consumes their output. Convert a Word document to PDF, then take its pages:

TypeScript
PHP
Python
Rust

const result = await client
  .file('./deck.docx')
  .convert('pdf')
  .split({ mode: 'page_groups', page_groups: 2 })
  .run({ maxWait: '10m' });
// Only the split's outputs: the intermediate PDF is not in result.artifacts.

$result = $client->file('./deck.docx')
    ->convert('pdf')
    ->split(['mode' => 'page_groups', 'page_groups' => 2])
    ->run(maxWait: '10m');
// Only the split's outputs: the intermediate PDF is not in $result->artifacts.

A split is the only operation in its job. Nothing can follow it: the split recipe has no further step methods, so a step after split() is a TypeScript compile error and an undefined method in PHP. Another operation that must run alone in its job, chained before the split, is refused at the split() call (multi_sole_op_unsupported).

File-first​

What run() returns​

Single operation​

Options​

PDF​

Video and audio​

Audio silence mode (beta)​

GIF​

Split after another step​

See also​