Lifecycle and files

Use the ID returned when you create a transcode to check its progress. You can also receive a verified webhook when it is ready, fails, is cancelled, expires, or is deleted.

Status and progress

While the status is preparing, processing_stage shows what is happening:

Video progress describes encoding, and reaches 100 only after publication. Encoding can finish before finalization and upload are complete.

Audio-only exports omit video encoding progress. Follow their status and stage instead. Treat ready as the signal that the file is available.

Read a transcode

Replace the example ID with your saved transcode ID. Run these calls on your server with the official SDK and a Project access token.

import Chunkify from '@chunkify/chunkify';

async function main() {
    const client = new Chunkify({
        projectAccessToken: 'My Project Access Token',
    });
    const transcoding = await client.transcodings.retrieve(
        'tcg_2G6MJiNz71bHQGNzGwKx5cJwPFS',
    );

    console.log(transcoding.status);
    for (const file of transcoding.files) {
        console.log(file.path, file.size);
    }
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});

from chunkify import Chunkify

client = Chunkify(
    project_access_token="My Project Access Token",
)
transcoding = client.transcodings.retrieve(
    "tcg_2G6MJiNz71bHQGNzGwKx5cJwPFS",
)

print(transcoding.status)
for file in transcoding.files:
    print(file.path, file.size)

<?php

use Chunkify\Client;

require_once __DIR__ . '/vendor/autoload.php';

$client = new Client(
    projectAccessToken: 'My Project Access Token',
);
$transcoding = $client->transcodings->retrieve(
    'tcg_2G6MJiNz71bHQGNzGwKx5cJwPFS',
);

var_dump($transcoding->status);
foreach ($transcoding->files as $file) {
    var_dump($file->path, $file->size);
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/chunkifydev/chunkify-go"
	"github.com/chunkifydev/chunkify-go/option"
)

func main() {
	client := chunkify.NewClient(
		option.WithProjectAccessToken("My Project Access Token"),
	)
	transcoding, err := client.Transcodings.Get(
		context.Background(),
		"tcg_2G6MJiNz71bHQGNzGwKx5cJwPFS",
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(transcoding.Status)
	for _, file := range transcoding.Files {
		fmt.Println(file.Path, file.Size)
	}
}

Use List transcodes to find requests by ID, Source, output storage, status, or creation time. List and detail responses use the same transcode resource schema.

Receive lifecycle events

Set up your webhook and verify signatures before trusting a notification. Each event contains a saved resource snapshot in data.transcoding.

Webhooks can arrive more than once or out of order. Store the transcode ID with your application record and retrieve current state when reconciling notifications.

Use the published files

files is empty until publication. Each file includes its ID, output storage and path, size, duration, and measured video or audio properties. Audio-only files omit video properties.

The response's format describes the accepted settings; file properties describe what was produced. Per-title requests keep per_title: true in format without reporting one predicted bitrate for the entire video.

A file's url is a signed download valid for at most ten minutes. Retrieve the transcode again for a fresh URL while the file remains available. Signing failures can omit this URL without changing a ready transcode's status.

A configured storage CDN supplies cdn_url. Use that URL for lasting delivery from your storage. The file's path is relative to the storage prefix saved when the transcode was created.

Video files can also have optional dashboard thumbnails. A thumbnail failure does not fail the media export. Follow Generate thumbnails when your application needs generated images or sprites.

Handle failure and cancellation

For a failed request, error.stage, error.code, and error.message describe the failure. Correct the input or settings and create another transcode when needed. A transcode that hasn't finished within your team's data retention period fails with the processing_deadline code and is then deleted.

Cancel a transcode cancels an unfinished request.

Cancellation is idempotent for an already cancelled request. It returns a conflict once processing is terminal or final publication has started.

Stopping processing can take time after cancellation is accepted. If deletion reports that processing is still stopping, retry deletion later.

Expiry and deletion

Outputs in Chunkify temporary storage expire 24 hours after publication, as shown by expires_at. The transcode then becomes expired: its files no longer have usable download or CDN URLs and may need a new transcode. Outputs in your storage don't expire.

Chunkify deletes every transcode record automatically. delete_at shows when, and a transcoding.deleted event is sent:

The data retention period is counted from when the transcode was created. A record is always kept for at least 3 days after it becomes ready, fails or is cancelled.

Automatic deletion removes only the Chunkify record; it never deletes outputs in your storage. Save any file locations or metadata your application needs before delete_at.

Delete a transcode removes a ready, failed, cancelled, or expired resource once processing and cleanup have stopped. By default, files in your storage are preserved.

Pass the delete_files=true query parameter to request output-file deletion as well. If storage deletion fails, records remain available for a retry, but files already deleted cannot be restored. Temporary output keeps its expiry after record deletion.