schema_version: 0.3
type: producer
identifier: avformat
title: FFmpeg Reader
version: 2
copyright: Copyright (C) 2003-2019 Meltytech, LLC
license: LGPL
language: en
url: http://www.ffmpeg.org/
creator: Charles Yates
contributor:
  - Dan Dennedy
tags:
  - Audio
  - Video
description: Read an audio and/or video file using FFmpeg.

notes: >
  This service uses mlt_cache to prevent many simultaneous, open instances
  of libavformat and libavcodec contexts, file handles, and threads in memory
  at the same time. Not only does it save on RAM usage, but kernels enforce
  maximum open file handles and threads per process. Without caching, large
  projects could easily run into these limits. The default producer cache
  size is in mlt_cache at size 4. When using mlt_multitrack, the size is
  adjusted automatically to be the number of tracks plus one if at least 4.
  This makes it rather dynamic and automatic; however, there are some service
  graph configurations or authoring scenarios that do not exclusively use the
  multitrack for multi-layer operations and may need a larger avformat
  producer cache size. One can set the environment variable
  MLT_AVFORMAT_PRODUCER_CACHE to a number to override and increase the size of
  this cache (or to lower it for limited use cases and seeking to minimize RAM).

bugs:
  - Audio sync discrepancy with some content.
  - Not all libavformat supported formats are seekable.
  - >
    Seeking is not always accurate. Sometimes it doesn't seek to I-frames so you
    may get junk for a few frames.
  - >
    More than 2 channels of audio more than 16 bits is not supported.

parameters:
  - identifier: resource
    argument: yes
    title: File/URL
    type: string
    description: |
      A file name specification or URL in the form:
      [{protocol}|{format}]:{resource}[?{format-parameter}[&{format-parameter}...]]
      For example, video4linux2:/dev/video1?width=320&height=240
      Note: on the bash command line, & must be escaped as '\&'.
      Use 'f-list' to see a list of supported file formats.
      Use 'vcodec-list' to see a list of supported video decoders.
      Use 'acodec-list' to see a list of supported audio decoders.
    readonly: no
    required: yes
    mutable: no
    widget: fileopen # could provide a button to use a file-open dialog 

  - identifier: audio_index # the name is the mlt_properties name
    title: Audio index
    type: integer
    description: >
      Choose the index of audio stream to use (-1 is off).
      When this value is equal to the maximum size of a 32-bit signed integer
      or the string "all" then all audio tracks are coalesced into a bundle of
      channels on one audio track.
    readonly: no
    mutable: no
    minimum: -1
    default: 0
    widget: spinner

  - identifier: video_index
    title: Video index
    type: integer
    description: Choose the index of video stream to use (-1 is off)
    readonly: no
    mutable: no
    minimum: -1
    default: 0
    widget: spinner

  - identifier: threads
    title: Decoding threads
    type: integer
    description: Choose the number of threads to use in the decoder(s)
    readonly: no
    mutable: no
    minimum: 0
    maximum: 4
    default: 1
    widget: spinner
    unit: threads # the unit is a label that appears after the widget

  - identifier: force_aspect_ratio
    title: Sample aspect ratio
    type: float
    description: Optionally override a (mis)detected aspect ratio
    readonly: no
    mutable: yes
    minimum: 0.001 # just a UI suggestion
    maximum: 9.999 # just a suggestion
    # no default property means it should be blank in the UI and not applied unless provided

  - identifier: source_fps
    title: Frame rate
    type: float
    scale: 2 # scale is the number of digits to display after the decimal point
    description: the framerate of the resource
    readonly: yes
    unit: frames/second

  - identifier: seekable
    title: Supports seeking
    type: boolean
    description: if the resource can seek
    readonly: yes

  - identifier: width
    title: Width
    type: integer
    unit: pixels
    readonly: yes

  - identifier: height
    title: Height
    type: integer
    unit: pixels
    readonly: yes

  - identifier: noimagecache
    title: Disable image caching
    type: boolean
    widget: checkbox

  - identifier: cache
    title: Number of images cache
    type: integer
    description: >
      By default, this producer caches images to facilitate YADIF deinterlace,
      which needs previous and next frames. Also, caching helps with frame-
      stepping within a player. The default number of images cached is supplied
      by the MLT framework, which is currently 4, but you can override it
      with this property. You can also disable caching by setting it to 0.
      If you are using parallel processing with YADIF deinterlacing, then
      you might need to increase caching to prevent inadvertent backward seeks.
      One can also set this value globally for all instances of avformat by
      setting the environment variable MLT_AVFORMAT_CACHE.

  - identifier: force_progressive
    title: Force progressive
    description: When provided, this overrides the detection of progressive video.
    type: boolean
    widget: checkbox

  - identifier: force_tff
    title: Force top field first
    description: When provided, this overrides the detected field order of interlaced video.
    type: boolean
    widget: checkbox

  - identifier: force_fps
    title: Force frame rate
    description: When provided, this attempts to override the detected frame rate of the video.
    type: float
    widget: checkbox

  - identifier: force_colorspace
    title: Force colorspace
    description: When provided, this overrides the detected colorspace of the video (Y'CbCr only).
    type: integer
    values:
      - 240 # SMPTE 240M
      - 601 # ITU-R BT.601
      - 709 # ITU-R BT.709

  - identifier: force_color_trc
    title: Force transfer characteristic
    description: >
      When provided, this overrides the detected gamma transfer of the video.
      See libavcodec AVColorTransferCharacteristic for values.
    type: integer

  - identifier: video_delay
    title: Video delay
    description: >
      Manually adjust A/V synchronization.
      A negative value advances the video instead of delaying it.
    type: float
    default: 0
    unit: seconds
    widget: timecode

  - identifier: reconnect
    title: Automatically reconnect?
    description: >
      Whether to attempt to automatically reconnect to a live source when a
      read failure occurs.
    type: boolean
    widget: checkbox

  - identifier: exit_on_disconnect
    title: Exit upon disconnection?
    description: >
      When this is set, the program will terminate with an error if a live source
      becomes disconnected.
    type: boolean
    widget: checkbox

  - identifier: mute_on_pause
    title: Mute on Pause
    description: >
      Mute the audio when the same frame is requested twice in a row.
    type: boolean
    default: 1
    widget: checkbox

  - identifier: seek_threshold
    title: Seek Threshold
    description: >
      Number of frames required to trigger a seek forward rather than continuous read
      when reading forward. This can be useful to optimize some applications which
      rely on accelerated reading of a media file or in cases where lack of I-frames
      cause libavformat to face issues in seeking and where user tries to minimize the
      number of seek calls.
    type: integer
    unit: frames

  - identifier: autorotate
    title: Auto-rotate?
    type: boolean
    description: >
      Whether to automatically compensate image orientation if the file is
      tagged with appropriate metadata and this resource has video/images.
    default: 1