Zencoder Encoding Settings: Thumbnails

Product(s)
Zencoder
Role(s)
API Developer
Topic(s)
Encoding Settings
API(s)
Zencoder API

This topic contains details for encoding settings related to video thumbnails.

thumbnails

thumbnails:Array or Hash

API Versions: V1, V2

Parent: outputs

Compatible Job Types: All

Example:

  • "thumbnails": [{}]
  • "thumbnails": {}

Description:

For every output, you can ask for one or more thumbnails.

Each output can have its own sets of thumbnails with unique size, base_url, and access_control set.

Multiple sets of thumbnails can be created for a single output by passing multiple thumbnail hashes within an array. If thumbnail options are passed in an array, a label must be set for set.

Set S3 access_control using the same options as you use for output videos.

Thumbnails are limited to 100 per-set. If more thumbnails would be generated given the options requested a warning will be added to the output and thumbnailing will stop when the limit is reached.

Note: There is no such thing as a thumbnail-only job. Specifying an output with just thumbnails will also create a billable, full-length mp4 with our default transcoding settings and upload it to temporary storage.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": [
        {
          "label": "first",
          "number": 10
        },
        {
          "label": "second",
          "interval_in_frames": 5000
        }
      ]
    }
  ]
}

See Also: label

label

label:String

API Versions: V1, V2

Parent: outputs / thumbnails

Compatible Job Types: All

Example: poster

Description:

A name for the thumbnail set. Required when requesting thumbnail sets in an array.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": [
        {
          "label": "poster"
        },
        {
          "label": "clips"
        }
      ]
    }
  ]
}

format

format:String

API Versions: V1, V2

Parent: outputs / thumbnails

Default: png

Valid Values: png or jpg

Compatible Job Types: All

Example: jpg

Description:

The format of the thumbnail image.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "format": "jpg"
      }
    }
  ]
}

number

number:Integer

API Versions: V1, V2

Parent: outputs / thumbnails

Valid Values: A positive integer

Compatible Job Types: All

Example: 3

Description:

A number of thumbnails to capture. Zencoder will grab evenly-spaced thumbnails across the whole duration of the file. So if you ask for 1 thumbnail, it will be near the middle of the file. Specifying 3 thumbnails on a 8 minute video will result in thumbnails at approximately 2, 4, and 6 minutes.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "number": 3
      }
    }
  ]
}

start_at_first_frame

start_at_first_frame:Boolean

API Versions: V1, V2

Parent: outputs / thumbnails

Default: false

Valid Values: true or false

Compatible Job Types: All

Example: true

Description:

When using the number option for thumbnail generation this will begin taking thumbnails with the first frame.

For example, when using if your video is 5 seconds long and you request 5 thumbnails using the number option, this will create thumbnails at 0s, 1s, 2s, 3s, and 4s. Normally it would grab thumbnails at 0.83s, 1.66s, 2.49s, 3.32s, and 4.15s.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "number": 5,
        "start_at_first_frame": true
      }
    }
  ]
}

interval

interval:Float

API Versions: V1, V2

Parent: outputs / thumbnails

Compatible Job Types: All

Example: 60

Description:

Take thumbnails at an even interval, in seconds. Zencoder will return one thumbnail for every N seconds of the file. So if you choose an interval of 60, and your input file is 12 minutes long, you’ll get back 12 thumbnails, each one on the minute.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "interval": 60
      }
    }
  ]
}

See Also: interval_in_frames

interval_in_frames

interval_in_frames:Float

API Versions: V1, V2

Parent: outputs / thumbnails

Compatible Job Types: All

Example: 120

Description:

Take thumbnails at an even interval, in frames. Zencoder will return one thumbnail for every N frames of the file. So if you choose an interval of 120, and your input file is 29.97 frames per second, you’ll get back thumbnails for approximately every 4 seconds.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "interval_in_frames": 120
      }
    }
  ]
}

See Also: interval

times

times:Array

API Versions: V1, V2

Parent: outputs / thumbnails

Compatible Job Types: All

Example: [0, 30, 60, 90]

Description:

An array of times, in seconds, at which to grab a thumbnail. Decimals are valid. So setting times to [12.5, 25] would grab two thumbnails, one at 12.5 seconds, and one at 25 seconds. This value must be an array of non-negative numbers.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "times": [0, 30, 60, 90]
      }
    }
  ]
}

aspect_mode

aspect_mode:String

API Versions: V1, V2

Parent: outputs / thumbnails

Default: preserve

Valid Values: preserve, stretch, crop, or pad

Compatible Job Types: All

Example: pad

Description:

The aspect mode to use when creating thumbnails.

  • preserve: By default, Zencoder will preserve the aspect ratio of the output video file, so if you submit widescreen content and ask for standard resolution, the thumbnail file will keep the widescreen aspect ratio, and will fit within the requested size.
  • stretch: When the aspect mode is "stretch", the thumbnail will exactly match the requested width and height, even if it distorts the image.
  • crop: This option tells Zencoder to "zoom in" to the thumbnail to match the requested size, by cropping pixels from the top/bottom or left/right.
  • pad: The pad option tells Zencoder to letterbox the thumbnail to match the requested frame size. Use this option to maintain the aspect ratio of the output video, but always get thumbnails of the same size.

Note: Due to the constraints of video scaling algorithms the dimensions of the thumbnails will be an even number. If you request thumbnails at 100x75, for example, you will get thumbnails that are 100x74.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "aspect_mode": "pad",
        "width": 200,
        "height": 200
      }
    }
  ]
}

See Also: size, width, and height

size

size:String

API Versions: V1, V2

Parent: outputs / thumbnails

Compatible Job Types: All

Example: 400x300

Description:

A target resolution for the thumbnails, like "160×120″. If no size is provided, thumbnails will be the same size as the output video. By default, we will preserve aspect ratio, so if the aspect ratio of this size parameter does not match the aspect ratio of the movie, the resulting file may not exactly match this size. If Stretch is set to true for the corresponding output file, then this thumbnail will also be stretched to fill the resolution.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "size": "400x300"
      }
    }
  ]
}

See Also: width, height, and aspect_mode

width

width:Integer

API Versions: V1, V2

Parent: outputs / thumbnails

Valid Values: A positive integer

Compatible Job Types: All

Example: 640

Description:

Thumbnail width. If no width is supplied, we will use the output file width, or scale to size or height setting.

Note that size takes priority over either width and height.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "width": 640
      }
    }
  ]
}

See Also: size, height, and aspect_mode

height

height:Integer

API Versions: V1, V2

Parent: outputs / thumbnails

Valid Values: A positive integer

Compatible Job Types: All

Example: 480

Description:

Thumbnail height. If no height is supplied, we will use the output file height, or scale to size or width setting.

Note that size takes priority over either width and height.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "height": 480
      }
    }
  ]
}

See Also: size, width, and aspect_mode

base_url

base_url:String

API Versions: V1, V2

Parent: outputs / thumbnails

Valid Values: A valid S3, Cloud Files, GCS, FTP, FTPS, or SFTP URL, minus filename. Format: s3://[bucket name]/[path] or ftp://[user]:[password]@[ftp.url]/[path]

Compatible Job Types: All

Example:

  • s3://my-output-bucket/
  • cf://username:api_key@container/path/
  • ftp://user:password@ftp.example.com/path/to

Description:

An output destination for thumbnails. If base_url is blank, we will store thumbnails in our Zencoder S3 bucket. Files stored in the Zencoder S3 bucket will be available after 24 hours. Note that the filenames are not unique between outputs (e.g. frame_0000.png), so the destination should be a unique directory or key prefix to avoid overwriting files.

FTP users: we try to write from the root of your server, so use an absolute path for your URL to ensure that we can write to your server successfully.

Notes on Credentials:

If you provide credentials via base_url they will be present in the urls appearing in requests to the job details, output details, etc. If credentials are stored with Zencoder they will not appear in urls in those responses.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "base_url": "s3://my-output-bucket/"
      }
    }
  ]
}

See Also: prefix and filename

prefix

prefix:String

API Versions: V1, V2

Parent: outputs / thumbnails

Default: frame

Compatible Job Types: All

Example:

  • thumbs
  • video_thumbnails

Description:

Thumbnail files will be exported with sequential filenames. However, you may specify a custom prefix for the thumbnail files. If no prefix is specified we’ll use frame. For example, if you use the prefix 'custom', the files exported would be named custom_0000.png, custom_0001.png, etc. Without a custom prefix they would be named frame_0000.png, frame_0001.png, etc.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "prefix": "thumbs"
      }
    }
  ]
}

See Also: base_url and filename

filename

filename:String

API Versions: V1, V2

Parent: outputs / thumbnails

Default: frame

Compatible Job Types: All

Example:

  • thumbnail_{{number}}
  • {{number}}_{{width}}x{{height}}-thumbnail

Description:

Thumbnail files can be given a filename based on several attributes. Attributes include number, padded-number, width, height, and size. It is not necessary to add a file extension, as it will be added by Zencoder based on the “format” option.

number or padded-number must be used, all others are optional. padded-number uses 4 spots (0000, 0001, etc).

height, width, and size will be based on the actual size of the generated thumbnail.

Example: {{number}}_{{width}}x{{height}}-thumbnail

Valid characters include letters, numbers, dashes, underscores, and the interpolated values.

Note: If you specify a filename, any specified prefix will be ignored.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "filename": "{{number}}_{{width}}x{{height}}-thumbnail"
      }
    }
  ]
}

See Also: base_url and prefix

public

public:Boolean

API Versions: V1, V2

Parent: outputs / thumbnails

Default: false

Valid Values: true or false

Compatible Job Types: All

Description:

The same as public for output files. See public for full documentation of this option.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "number": 10,
        "public": true
      }
    }
  ]
}

See Also: access_control

access_control

access_control:Array

API Versions: V1, V2

Parent: outputs / thumbnails

Valid Values: An array of hashes containing two setings: grantee and permission.

Compatible Job Types: All

Description:

The same as access_control for output files. See access_control for full documentation of this option.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "access_control": [
          {
            "permission": "READ",
            "grantee": "someone@example.com"
          }
        ]
      }
    }
  ]
}

See Also: public, grantee, and permission

grantee

grantee:String

API Versions: V1, V2

Parent: outputs / thumbnails / access_control

Valid Values: A valid S3 grantee (email, ID, or URI)

Compatible Job Types: All

Description:

The same as grantee for output files. See grantee for full documentation of this option.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "access_control": [
          {
            "permission": "FULL_CONTROL",
            "grantee": "cdc7931a9574b1055d5b76112021d0e9"
          }
        ]
      }
    }
  ]
}

See Also: access_control and permission

permission

permission:String

API Versions: V1, V2

Parent: outputs / thumbnails / access_control

Valid Values: A string or array of strings containing: READ, READ_ACP, WRITE_ACP, or FULL_CONTROL

Compatible Job Types: All

Description:

The same as permission for output files. See permission for full documentation of this option.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "access_control": [
          {
            "permission": "FULL_CONTROL",
            "grantee": "cdc7931a9574b1055d5b76112021d0e9"
          }
        ]
      }
    }
  ]
}

See Also: access_control and grantee

rss

rrs:Boolean

API Versions: V1, V2

Parent: outputs / thumbnails

Default: false

Valid Values: true or false

Compatible Job Types: All

Description:

The same as rrs for output files. See rrs for full documentation of this option.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "rrs": true
      }
    }
  ]
}

headers

headers:Hash

API Versions: V1, V2

Parents: outputs OR thumbnails

Compatible Job Types: All

Example: { "Content-Type": "binary/octet-stream" }

Description:

HTTP headers to send with your thumbnails when we upload them. This feature is currently supported when using S3 and Cloud Files.

Zencoder supports setting a limited subset of these headers: Cache-Control, Content-Disposition, Content-Encoding, Content-Type, Expires, x-amz-acl, x-amz-storage-class, x-amz-server-side-encryption, and x-amz-meta-*.

Headers will be ignored when an output location is not specified.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "headers": {
          "Content-Type": "binary/octet-stream",
          "x-amz-acl": "public-read-write"
        }
      }
    }
  ]
}

credentials

credentials:String

API Versions: V2

Parent: outputs / thumbnails

Compatible Job Types: All

Example: ftp_dev_server

Description:

References the nickname of saved credentials to use for transfer, which are managed in the Account Credentials section.

NOTE: Credentials for syndication services are for output videos only.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "base_url": "ftp://ftp.example.com/thumbnails/",
        "credentials": "ftp_dev_server"
      }
    }
  ]
}

See Also: base_url

parallel_upload_limit

parallel_upload_limit:Integer

API Versions: V1, V2

Default: 30 for S3, 10 for all other destinations.

Valid Values: An integer between 1 and 30

Compatible Job Types: All

Example: 5

Description:

The maximum number of simultaneous uploads made when uploading thumbnails.

This may speed up transfer times, depending on the bandwidth at your remote server. Be aware that more connections can place a heavier load on the server. If you have trouble with upload timeouts, or want to prevent Zencoder from using too much bandwidth when uploading files, set this to 1.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "thumbnails": {
        "base_url": "ftp://ftp.example.com/thumbnails/",
        "parallel_upload_limit": 5
      }
    }
  ]
}