schema_version: 0.1
type: consumer
identifier: xml
title: XML
version: 1
copyright: Ushodaya Enterprises Limited
creator: Dan Dennedy
license: LGPLv2.1
language: en
tags:
  - Audio
  - Video
description: >
  Serialise the service network to XML.
  See docs/mlt-xml.txt for more information.

notes: >
  If you set a data property beginning with (and longer than) "xml_retain" on
  the service connected to this consumer where the data is a mlt_service
  pointer, then the pointed at service will also be serialized before the
  connected service. This can be useful, for example, to save a playlist as
  a media bin along with a multitrack. You can serialize more than one of these
  additional services by setting more than property, each with a unique key
  beginning with "xml_retain".

bugs:
   - Untested arbitrary nesting of multitracks and playlists.
   - >
     Property "id" is generated as service type followed by number if no
     property named "id" exists, but it fails to guarantee uniqueness.

parameters:
  - identifier: resource
    argument: yes
    title: File
    type: string
    description: >
      The name of a file in which to store the XML.
      If the value does not contain a period (to start an extension), then
      the value is interpreted as the name of a propery in which to store the
      XML. This makes it easy for an application to use the consumer to
      serialize a service network and retrieve the XML in-memory.
    readonly: no
    required: no
    mutable: no
    default: stdout
    widget: fileopen

  - identifier: all
    title: Process all frames
    type: integer
    description: >
      Without this option, the XML consumer does not process any frames
      and simply serializes the service network. However, some filters (.e.g,
      videostab) require two passes where the first pass performs some
      analysis and stores the result in a property. Therefore, set this
      property to 1 (true) to cause the consumer to process all frames
      before serializing to XML.
    minimum: 0
    maximum: 1
    default: 0

  - identifier: title
    title: Title
    type: string
    description: >
      You can give the composition a friendly name that some applications may use.

  - identifier: root
    title: Base path
    type: string
    description: >
      If a file name in the XML is relative, but not relative to the current
      XML file's directory, then you can set the directory to which it is
      relative here.

  - identifier: no_meta
    title: Exclude meta properties
    type: integer
    description: >
      Set this to disable the output of properties with the prefix "meta."
    minimum: 0
    maximum: 1
    default: 0
    widget: checkbox

  - identifier: time_format
    title: Time format
    type: string
    description: Output time-based values as timecode or clock formats.
    values:
      - frames
      - smpte # or SMPTE
      - timecode # same as smpte
      - clock # or CLOCK
    default: frames
    widget: dropdown

  - identifier: store
    title: Include property prefix
    type: string
    description: >
      To save additional properties that MLT does not know about, supply an
      application-specific property name prefix that you are using.