#Overview

Output path templates control the directory structure and file naming for transcoded outputs. Instead of manually specifying full paths for every output, you define templates with variables like {job_id} and {resolution} that are resolved automatically at encoding time.

Transcodely uses a 4-level template hierarchy that lets you set sensible defaults at the origin level and override them per-job or per-output as needed.

#Template Variables

Use these variables in any path template. They are resolved at job creation time:

#Template Hierarchy

Templates are resolved in priority order. The first template found is used:

#Setting Templates at Each Level

Per-output template (highest priority):

{
  "outputs": [
    {
      "type": "mp4",
      "video": [{ "codec": "h264", "resolution": "1080p", "quality": "standard" }],
      "path_template": "featured/{job_id}/main"
    }
  ]
}

Job-level template (applies to all outputs without their own template):

{
  "output_path_template": "{date}/{job_id}/{codec}_{resolution}",
  "outputs": [
    {
      "type": "mp4",
      "video": [{ "codec": "h264", "resolution": "1080p", "quality": "standard" }]
    },
    {
      "type": "mp4",
      "video": [{ "codec": "h264", "resolution": "720p", "quality": "standard" }]
    }
  ]
}

This produces paths like:

2026-02-28/job_abc123/h264_1080p.mp4
2026-02-28/job_abc123/h264_720p.mp4

Origin template (set when creating the origin):

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -d '{
    "name": "CDN Output Bucket",
    "permissions": ["write"],
    "path_template": "{date}/{job_id}/{resolution}",
    "gcs": {
      "bucket": "my-cdn-bucket",
      "credentials": {
        "service_account_json": "<sa-key contents>"
      }
    }
  }'

All jobs using this origin will inherit the template unless they specify their own.

#Path Computation

The final file path depends on whether the output is a regular file or a streaming package.

#Regular Outputs (MP4, WebM, MKV, MOV)

The resolved template gets the file extension appended:

{resolved_template}.{extension}

Example: Template {job_id}/{codec}_{resolution} with H.264 at 1080p in MP4:

job_abc123/h264_1080p.mp4

#Streaming Outputs (HLS, DASH)

Streaming outputs add the format directory and manifest filename:

{resolved_template}/{format}/{manifest}.{extension}

Example: Template {job_id}/{codec}_{resolution} with HLS:

job_abc123/h264_1080p/hls/master.m3u8

Example: Template {date}/{job_id} with DASH:

2026-02-28/job_abc123/dash/manifest.mpd

#Collision Detection

When multiple outputs in a job resolve to the same path, Transcodely detects the collision. The behavior depends on whether the template was explicitly set by you or implicitly inherited:

#Auto-Fix Example

If your origin template is {date}/{job_id}/{resolution} and you create two outputs at the same resolution:

{
  "outputs": [
    {
      "type": "hls",
      "video": [{ "codec": "h264", "resolution": "1080p", "quality": "standard" }]
    },
    {
      "type": "hls",
      "video": [{ "codec": "h265", "resolution": "1080p", "quality": "standard" }]
    }
  ]
}

Without auto-fix, both outputs would resolve to 2026-02-28/job_abc123/1080p/hls/master.m3u8. The API detects this and appends /{output_id} to each path:

2026-02-28/job_abc123/1080p/out_001/hls/master.m3u8
2026-02-28/job_abc123/1080p/out_002/hls/master.m3u8

#Fixing Explicit Collisions

If you set a job-level or output-level template that causes collisions, you must resolve it yourself. Add a distinguishing variable:

{
  "output_path_template": "{job_id}/{codec}_{resolution}",
  "outputs": [
    {
      "type": "mp4",
      "video": [{ "codec": "h264", "resolution": "1080p", "quality": "standard" }]
    },
    {
      "type": "mp4",
      "video": [{ "codec": "h264", "resolution": "1080p", "quality": "premium" }]
    }
  ]
}

This would fail because both resolve to job_abc123/h264_1080p.mp4. Fix it by adding {quality}:

{
  "output_path_template": "{job_id}/{codec}_{resolution}_{quality}"
}

Now the paths are unique:

job_abc123/h264_1080p_standard.mp4
job_abc123/h264_1080p_premium.mp4

#Custom Manifest Names

For HLS and DASH outputs, you can customize the manifest filename:

{
  "type": "hls",
  "video": [
    { "codec": "h264", "resolution": "1080p", "quality": "standard" }
  ],
  "hls": {
    "manifest": "index",
    "variant_pattern": "video_{resolution}"
  }
}

This produces index.m3u8 instead of the default master.m3u8, and variant playlists named video_1080p.m3u8 instead of h264_1080p.m3u8.

For DASH:

{
  "type": "dash",
  "dash": {
    "manifest": "stream"
  }
}

This produces stream.mpd instead of manifest.mpd.

#Base Path

Origins also have a base_path field that prefixes all paths. This is applied before the template:

{origin.base_path}/{resolved_template}.{extension}

Example: Origin with base_path: "videos/" and template {job_id}/{resolution}:

videos/job_abc123/1080p.mp4

Use base_path to keep Transcodely outputs in a specific directory within your bucket.

#Best Practices