.. Copyright (c) 2008-2016 OpenShot Studios, LLC
 (http://www.openshotstudios.com). This file is part of
 OpenShot Video Editor (http://www.openshot.org), an open-source project
 dedicated to delivering high quality video editing and animation solutions
 to the world.

.. OpenShot Video Editor is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

.. OpenShot Video Editor is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
 along with OpenShot Library.  If not, see <http://www.gnu.org/licenses/>.

.. _export_ref:

Export / Render
===============

OpenShot Cloud API can create many different types of final renders, which we call *Exports*. Create videos,
sequences of images, audio waveforms, and/or audio files. By default an export uses
the parent project settings for ``width``, ``height``, ``FPS (frames per second)``, ``sample_rate``, ``channels``, and
``channel_layout``. But all these attributes can be overwritten on any Export, by using the ``json`` attribute.
See :ref:`export_endpoint_ref` for more information. See :ref:`frame_numbers_ref` for more information on calculating frame
numbers (i.e. start_frame, end_frame).

Compatibility
-------------
Every device (computer, phone, tablet, game system, television) has certain formats, codecs, and FPS which it supports.
OpenShot Cloud API supports a large number of audio and video codecs (based on FFmpeg). In general though, we recommend
using the default video export settings: MP4 format (``mp4``), h.264 video codec (``libx264``), and AAC audio codec
(``aac``), which is compatible with a very large group of devices.

Video (Default)
---------------
The default export type is **video**, which creates a final rendered video file. The video will contain both a video
and audio track, and the dimentions can be overwritten in the *Json* field.

.. code-block:: javascript
  :caption: **Request Data**

  {
      "export_type": "video",
      "video_format": "mp4",
      "video_codec": "libx264",
      "video_bitrate": 8000000,
      "audio_codec": "aac",
      "audio_bitrate": 1920000,
      "start_frame": 1,
      "end_frame": null,
      "project": "http://cloud.openshot.org/projects/PROJECT_ID/",
      "webhook": "",
      "json": {},
      "status": "pending"
  }

.. image:: images/export_video.png

Audio Only
----------
To create an audio-only file, use the following settings. No video track will be included.

.. code-block:: javascript
  :caption: **Request Data**

  {
      "export_type": "audio",
      "video_format": "mp3",
      "video_codec": "n/a",
      "video_bitrate": 0,
      "audio_codec": "libmp3lame",
      "audio_bitrate": 1920000,
      "start_frame": 1,
      "end_frame": null,
      "project": "http://cloud.openshot.org/projects/PROJECT_ID/",
      "webhook": "",
      "json": {},
      "status": "pending"
  }

.. image:: images/export_audio_only.png

Image Sequence
--------------
To create a single thumbnail, or sequence of images, use the following settings. This will return a single *zip* file,
which contains all images requested. It currently supports PNG and JPG. The framerate and size can be overwritten in
the *Json* field.

.. code-block:: javascript
  :caption: **Request Data**

  {
      "export_type": "image",
      "video_format": "%05d.png",
      "video_codec": "png",
      "video_bitrate": 8000000,
      "audio_codec": "n/a",
      "audio_bitrate": 0,
      "start_frame": 1,
      "end_frame": null,
      "project": "http://cloud.openshot.org/projects/PROJECT_ID/",
      "webhook": "",
      "json": {},
      "status": "pending"
  }

.. image:: images/export_image_sequence.png

Audio Waveform
--------------
To generate a waveform image use the following settings. You can adjust the height and width, and select PNG or JPG
as the video codec. Wave color and background color can be overwritten in the *Json* field.

.. code-block:: javascript
  :caption: **Request Data**

  {
      "export_type": "waveform",
      "video_format": "png",
      "video_codec": "png",
      "video_bitrate": 8000000,
      "audio_codec": "n/a",
      "audio_bitrate": 0,
      "start_frame": 1,
      "end_frame": null,
      "project": "http://cloud.openshot.org/projects/PROJECT_ID/",
      "webhook": "",
      "json": { "wave_color": "Blue", "wave_background_color": "#000000" },
      "status": "pending"
  }

.. image:: images/export_waveform.png