.. 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/>.

.. _release_notes_ref:

Release Notes
=============
The following releases are available for the OpenShot Cloud API. It is recommended you use the most current release
when starting up a new instance. See :ref:`upgrade_ref` instructions.

.. _release_latest_ref:

Latest
------
- **3.1.0** (in-development)


  * Added **/swagger-ui/** and **/redoc/** to better document all available API endpoints. See :ref:`schema_documentation_ref`.
  * New Schema generation for **OpenAPI (3.0.3)**: /schema/ endpoint for Yaml schema file
  * Stricter URL regex for IDs (must be integer in URL patterns). This was required for proper schema generation.
  * Refactored **language codes** into a common ENUM (for improved schema generation)
  * New unit tests to verify duplicate file uploads do not crash
  * Protections around CopyFile serializer (prevent crashes in certain circumstances)
  * New environment variable to prevent OpenAI Whisper file permission errors
  * Moved the following endpoints (grouping under /settings/ to clean-up API):

    * `/aws/validate` -> `/settings/aws/validate`
    * `/azure/validate` -> `/settings/azure/validate`
    * `/google/validate` -> `/settings/google/validate`

.. _release_history_ref:

History
-------
- **3.0.3**

  * Refactor QApplication initialization code and set XDG_RUNTIME_DIR to temp folder
  * Fixing regression which displays debug [ERROR] messages during the initial run of `config-openshot-cloud`
  * Improving `config-openshot-cloud` command to default CLOUD_HTTP_HOST to the public IP detected
  * Updating Google Cloud documentation, GCP marketplace URL, diagram, and instructions

- **3.0.2**

  * Adding Google Cloud Support (Pub/Sub & Cloud Storage integration, currently pending approvals for Google Cloud Marketplace)
  * Allow effects to be applied BEFORE or AFTER a clip's keyframes (very useful for Mask effects, libopenshot C++)
  * Added auto-resize capability to Crop effect (to maximize the size of the cropped area in the video)
  * Improving Shutdown behavior of video processing worker script (handle SIGTERM signal correct, to cleanly and quickly shutdown any video rendering, and mark the export as failed)
  * Fixed audio pops in certain scenarios (when down sampling from 48000 to 44100 sample rate, libopenshot C++)
  * More verbose logging around webhooks, to document failures and make troubleshooting easier
  * Adding lock around SetCache method to prevent crash (libopenshot C++)
  * Fixed large memory leak on Clips where we were not clearing cache on Close or forcing Close on destruction (libopenshot C++)
  * Fixed caption parsing to better support numeric caption text (libopenshot C++)
  * Add additional logging to audio device initialization (libopenshot C++)

- **3.0.1**

  * Fixed multiple **WEBM decoding** issues (libopenshot would sometimes freezes or experience decoding artifacts with certain WEBM files)
  * Fixed bug causing **audio-only clips** to cover up images on lower tracks (i.e. audio clips were outputting a black opaque image)
  * Fixed regression with :ref:`fonts_endpoint_ref` endpoint (**permission issue** when adding new fonts to `/usr/share/fonts/`)
  * **Expanded** list of installed **font** files (3.0.0 release had a limited # of fonts)
  * Fixing issue with **bash history** file (to correctly truncate for **Azure technical validation**)

- **3.0.0**

  * Added new :ref:`file_transcribe_endpoint_ref` endpoint (powered by OpenAI Whisper AI) to **transcribe voice and audio** files. Can also translate transcription to English. Generates VTT/Subrip formatted caption text.
  * Added new :ref:`clip_captions_endpoint_ref` endpoint, which adds VTT/Subrip formatted **caption text** to a Clip. This endpoint can also import transcription data from the related File object (if transcription data is available).
  * Improved **time re-mapping** (slow down, speed up - especially when using Bezier keyframes)
  * Improved **audio reversing** code (for playing videos in reverse)
  * Improvements to **audio-only** clip **visualizations** - which can now show waveforms and utilize Caption effects (for example, audio transcriptions on top of animated waveform)
  * Updates to **default Caption Effect** properties (smaller font size, smaller left/right margins). Also fixed many bugs with VTT/Subrip regular expression parsing - increasing compatibility with more caption data
  * Improved calculation for **render update frequency** - to use "time" instead of "frames". This reduces the # of progress updates which happen during a render, especially for high FPS renders, reducing HTTP traffic. The setting ``SECONDS_BETWEEN_UPDATES`` is now defaulted to 3 seconds.
  * Updated **supported image formats**: `.bmp, .dpx, .exr, .gif, .jpg, .jpeg, .pam, .pbm, .pcx, .pgm, .png, .pnm, .ppm, .psd, .sgi, .svg, .tga, .thm, .tif, .tiff, .webp, .xbm, .xpm, .xwd`
  * **Latest security patches** and updates. Updated Django to 4.1.7, DFR to 3.14.0, and many other Python packages.
  * Fixed **Zombie threads** left behind after a video export, which over time can cause VM failures due to resource limits.
  * **Large Memory Leak** fixed after each video export is completed. This was causing an increase in RAM usage over time, and especially noticeable on higher resolution exports.
  * **New Worker Clean-Up** which removes old cached project assets on worker instances, after an export is completed. This ignores pending and in-progress exports. This can be disabled with a value of 0 (during configuration of instance).
  * **New Automated Project Clean-Up** which removes old projects after X days. This can be disabled with a value of 0 (during configuration of instance).
  * Improved cron schedule (new clean-up tasks, optimized schedule to reduce CPU and collisions)
  * **New documentation** regarding automated clean-up tasks. See :ref:`manage_server_files_aws_ref` and :ref:`manage_worker_files_aws_ref`.
  * Updated base OS to **Ubuntu 22.04 Minimal LTS** (Jammy)

- **2.3.0**

  * **Async and PTS Timestamp improvements** which fixes many bugs related to out-of-order frames, repeated frames, invalid durations, or missing frames at the beginning or end of a video file. This also dramatically improves performance on certain types of video/audio files that contain missing packets/frames.
  * **Caption Improvements** Many big updates to our Caption effect (including auto center alignment, background color now stays behind text, adjustable line spacing, and many bug fixes)
  * **Improved Merging** Fixed bug in :ref:`merge_endpoint_ref` endpoint, which prevented the `original_merge_id` from being added to merged clips and effects.
  * **Removed Validation** which prevented clips from being longer than their file's duration. It is now completely valid to extend a clip past the file duration, and it will now freeze frame on the final frame (if needed) with muted audio.
  * **Improved Text-Replace** Fixed bug with /text-replace/ endpoint, to prevent file caching on distributed worker instances (i.e. the file name is now changed after calling this function)
  * **Improved Export Failure Detection** Added new statuses to the export process (``preparing`` & ``finalizing``) for more visibility into the export process, and with this additional context we have improved our detection of failures (which prevents accidental export failures).
  * **Bug fix** Actions (on Projects, Clips, Files, and Exports) now use the correct and current protocol (i.e. https vs http)
  * **Bug fix** /files/find/ endpoint has been fixed to correctly include embedded clip masks (this would fail previously on worker instances which could not locate the mask files)
  * **Reduced Memory Usage** By reducing the default QUEUE_MESSAGES_PER_SCRIPT setting from 12 to 4 (causing the render script to restart more often, clearing server memory)
  * Updates to **documentation**

- **2.2.2**

  * **Memory improvements** (i.e. reduced memory needed for Exports)
  * Memory **leak fixed** (when using longer 60+ min duration clips in different FPS than the project)
  * **Auto Retry** any Export which has been failed by a scheduled cron cleanup job (i.e. pending for too long, hard crash, cloud scaling termination). *Only retires 1 time.*
  * **Launch** of new `Demo UI (simple-editor) <https://cloud.openshot.org/apps/simple-editor/>`_. MIT licensed, **open-source**, and a great jump-start to building your own
    custom web UI!
  * New **Demos** page included in the **documentation**
  * Fixed big regression with **CORS support** in v2.2.1 (moving from Apache to Python CORS support)
  * Improved **Basic Auth**: No longer return ``www-authenticate: Basic realm="api"`` response header if ``X-Requested-With`` request header is
    ``XMLHttpRequest``. This prevents the web browser from prompting the user during 401 Basic auth failures when using
    XMLHttpRequest's from the browser/JavaScript.
  * **Cron jobs** only run on instances configured as 'server' or 'both' (ignoring 'worker' instances)
  * Increasing # of foreign key values in dropdowns to 3000 (up from 1000), when using the default REST web UI.
  * Refactor how cloud environment is detected and loaded (development vs production)
  * New :ref:`token_endpoint_ref` endpoint (to **retrieve a token** for a specific user)

- **2.2.1**

  * Fixed regression in ``config-openshot-cloud`` command (causing all custom username and passwords to be invalid)

- **2.2.0**

  * Updated Chroma Key effect to support new color modes (using babl color library) - Improving Chromakey quality in many cases.
  * Updated ReSVG library, for improved SVG compatibility and lots of quality of life updates for SVG rendering
  * Added new :ref:`cancel_endpoint_ref` endpoint, for canceling `pending` and `in-progress` video exports.
  * Updated worker script to process 12 videos before exiting (by default). The script will restart (to clear memory) after this happens.
  * Added support for a variety of export bitrate formats, instead of just bytes (`7600000`, `7.6 Mb/s`, `7600 kb/s`, `5 crf (0-63)`, `5 cqp (0-63)`, `20 qp (0-255)`)
  * Improved support for @transitions and @emojis in File and Clip paths.
  * Added support for all emojis in OpenShot 2.6.x (@emojis file paths will correctly resolve now)
  * Updated transition files (all transitions in OpenShot 2.6.x)
  * Added new :ref:`project_format_endpoint_ref` endpoint, for downloading offline EDL or XML (Final Cut Pro) project files
  * Fixed regression with copied projects rendering on worker instances (where some files could be located in the wrong folder)
  * Improved /files/find/ endpoint to only return unique files (improving performance on projects with many duplicate resources)
  * Updated libopenshot and libopenshot-audio libraries, improved performance
  * Fixed SCALE_NONE scaling bugs resulting in images that were too large (this was a regression in libopenshot)
  * Added Auto-Scaling Azure documentation (Scale Sets)
  * Adding many audio-only effects: (compressor, expander, distortion, delay, echo, noise, EQ, robot, whisper)
  * Fixed `config-openshot-cloud` issue on Azure, which would not disable the worker process on a server instance (causing the worker to continue processing exports on the server)
  * Block most signals from triggering on upgrade (i.e. loaddata)
  * Improved error logging on worker / video processing script
  * Improved documentation for manually upgrading between API versions
  * Migration helper script for older API customers (migrating from an older DB schema)
  * Improved thumbnail endpoints, which correctly size thumbnails to the requested dimensions.
  * Fixed small bug in /files/ID/download endpoint, where certain file names were incorrectly escaped
  * Removing redundant call to /exports/ID/ on worker script (small performance improvement)
  * Webhooks are now sent with `application/json` content-type by default (instead of form-urlencoded). Legacy support can be toggled (for `application/x-www-form-urlencoded` if needed by including ``"json": { "webhook-form-urlencoded": true}`` in your export record).
  * Failed exports will now include an error message in the Export record: ``"json": { "error": "Something went very wrong!"}``
  * Clips with `time` keyframes no longer validate the `end` property (i.e. it can be longer than the duration in these cases)
  * Improved unit tests to ensure better quality and to verify all bug fixes
  * Fixed PATCH CORS error, where certain policies would prevent PATCH from working

- **2.1.1**

  * Fixed regression with audio-only exports (now both video and audio exports support mp4_faststart)
  * Updated documentation related to aac audio codecs
  * Updated list of available effects (to dynamically list all libopenshot effects)
  * Added support for HTTPS load balancers (HTTP_X_FORWARDED_PROTO)

- **2.1.0**

  * Massive performance improvements in video compositing, encoding, and decoding processing
  * Audio crackling/popping fixes on libopenshot, which affected certain sample rate and frame rate conversions.
  * Audio crash fixed which would cause certain channel layout (i.e. MONO) to freeze and crash.
  * Added a C# example script in the getting_started section
  * Added :ref:`merge_endpoint_ref` endpoint for combining two projects. This is especially useful for combining template projects.
  * Exif support for most image formats (auto-rotation)
  * Support for Captions effect (single VTT/subrip string which can display text through-out a video, including animation)
  * Updated libopenshot and libopenshot-audio libraries, improved performance (pre-multiplied alpha channels)
  * Improved support for videos containing an alpha channel
  * Added `interlaced` and `top_field_first` Export json attributes (that can be overwritten)
  * mp4_faststart enabled for video exports (moov atom is located at the beginning of the file) to enable streaming
  * Fixed bug when webhook url called contains localhost/private IP instead of public http host
  * Added logging to all cases in which os.unlink is called
  * Added validations to /clips/ POST, PUT, AND PATCH endpoints, to ensure clips do not exceed the file duration, and other common issues

- **2.0.0**

  * Introduced the concept of shallow copy (physical media file is not duplicated) in files
  * Improved support for nested Clip effects and effect paths, including /validate/, /download/, and /load/ improvements related to clip effects.
  * /project/ID/copy/ and /files/ID/copy endpoint by default perform a shallow copy
  * For performing PUT PATCH DELETE on /files/ID/ endpoint, `project` is now a required parameter for files being shared in more than one projects
  * Introduced the /projects/ID/files/ID/ endpoint that supports GET PUT PATCH DELETE
  * To update a file for all projects sharing the file, pass `update_all=true` as a query string parameter in the PUT PATCH DELETE methods on /file/ID/. User must have access to all of the related projects
  * When PUT PATCH is executed on either /files/ID/ (with project param) or /projects/ID/files/ID/ on an file that is being shared by more than one project, a new file object is created and the previous file is de-referenced from the project.files
  * With this change, it is possible for files of one project to exist in the folder of another project (even deleted projects)
  * Refactored signals into a new file
  * Improved stability, and many new unit tests to ensure quality

- **1.3.0**

  * Full support for image sequences (with transparency), such as Blender animations, animated overlays, etc...
    * /cloud-admin/ is now a fully supported environment, allowing full API functionality from the Admin.
  * Added /storage/ endpoints for calculating size of files and projects (:ref:`filestorage_ref` and :ref:`projectstorage_ref`)
  * Added ability to mirror all API media files in cloud storage (so the API server can remove local files and re-download them when needed)
  * Fixed many bugs related to saving/uploading/changing media files for File objects
  * Added improved ability to use local Django models with custom applications
  * Improved testing, automation, and quality improvements
  * Updated verbiage and images for Azure support (including new documentation pages)
  * Fixed bug which marked almost completed (>99% progress) exports as failed
  * Fixed bug in /projects/ID/copy/ endpoint, which prevented the copying of custom effect masks
  * Fixed bug when loading a \*.zip containing a __MACOS hidden folder
  * Fixed bug in orphaned file clean-up, which would delete custom effect masks
  * Fixed bug with OPTIONS configuration (was throwing error)
  * Fixed bug with config-openshot-cloud resetting the wrong superuser account password
  * Fixed bug where S3 uploads had incorrect/no content-type set
  * Added documentation for storage scaling support (Amazon Elastic File System: EFS)

- **1.2.3**

  * Added retry logic for download files from URL or S3 (when creating File objects)
  * Added retry logic when inspecting newly uploaded File objects
  * Improved error handling and logging when invalid or corrupted File objects are used
  * Added secure download endpoints for media files (:ref:`download_file_ref` and :ref:`export_file_ref`)
  * Workers now fallback to secure download endpoints, if direct media URLs are invalid (i.e. if you manually disable them in Apache for security)
  * Added new configuration setting to override HTTP_HOST (and force all URLs to use any public URL you want). This is especially useful for webhooks (which often refers to http://127.0.0.1).
  * Improvements to `config-openshot-cloud` command, messages, formatting, AWS/Azure cloud detection, and support for **Azure cloud backend** (Queue and Blob storage)
  * Added Azure Blob Storage support to :ref:`File <azure_download_endpoint_ref>` and :ref:`Export <export_azure_upload_ref>` endpoints (Exports can support both S3 and Azure Blob storage concurrently)
  * Added Azure Queue Storage support for Export queue management (OpenShot API now supports both SQS or Azure Queues... just not at the same time)

- **1.2.2**

  * Improved :ref:`copy_file_ref` endpoint, which now has an optional "project" parameter. This can be used to copy a file to a different project.
  * Much improved `config-openshot-cloud` command (formatting and layout improvements, ability to register for support)
  * Fixed Effect (Mask) bug where workers were not able to download a custom asset
  * Added new unit tests with more coverage and many additional edge cases handled
  * Upgraded libopenshot C++ library with latest improvements and bug fixes (including a serious SVG mask related bug)
  * Experimental hardware acceleration support in libopenshot (requires instances with hardware encoders/decoders)
  * More reliable asset downloading between workers and server (retry logic and improved error reporting)
  * Enable CORS (cross-origin resource sharing) by default (can be disabled in `/etc/apache2/sites-available/openshot.conf`)
  * Upgraded boto3 module, for improved AWS S3/SQS support (added support for more regions: ap-south-1)
  * Updated system libraries and applied security updates
  * Improved documentation (REST methods, frame # calculations, suggested instance types, upgrade instructions)

- **1.2.1**

  * Fixed regression with :ref:`copy_file_ref` endpoint, where original file media was removed
  * Fixed regression with :ref:`copy_project_ref` endpoint, where original file media was removed
  * Improved documentation for token authentication

- **1.2.0**

  * Upgrade from Ubuntu 16.04 LTS to 18.04 LTS
  * All libraries and frameworks updated (including Qt, FFmpeg, resvg, and Python)
  * Improved SVG rendering (due to updated Qt dependency)
  * Fixed SVG right alignment bug (due to updated Qt dependency)

- **1.1.1**

  * Much improved SVG rendering (using resvg library). Supports more of the SVG language than our previous Qt SVG library.
  * Fixed bug with export object, where webhooks and S3 options were being clobbered at the end of an export.
  * Fixed S3 upload failures
  * Added more unit tests to validate S3 uploading and webhooks
  * Added new :ref:`fonts_thumbnail_endpoint_ref` endpoint, to preview all installed fonts
  * New default font, when the API can not find an installed font

- **1.1.0**

  * Replaced ZMQ queue with AWS SQS (for more reliable and scalable queue handling of video exports). Requires IAM user and permissions (AmazonSQSFullAccess & AmazonS3FullAccess).
  * Worker queue processing now restarts after exports are complete (clearing memory)
  * Worker file synchronizing is much faster (and more optimized)
  * Fixed :ref:`load_endpoint_ref` endpoint bug when loading ZIP archive of project files.
  * New :ref:`fonts_endpoint_ref` endpoint for adding new Font files dynamically (POST method now accepted)
  * Memcached replacing local memory caching (more efficient caching)
  * :ref:`projects_files_find_ref` endpoint has been modified, to provide the media URL and file object URL
  * Updated documentation with new AWS SQS instructions

- **1.0.10**

  * Improved API performance (less DB queries per request)
  * File updating bug fix (updating the media of a file would break)
  * New libopenshot version (fixes some codec issues, improved performance, better detection of various media formats)

- **1.0.9**

  * Added :ref:`copy_file_ref` endpoint to Project and File objects
  * Added :ref:`download_endpoint_ref` endpoint for projects (ZIP archive of entire project with relative paths)
  * Added :ref:`textreplace_ref` endpoint for File objects (for easily editing SVG or text-based files)
  * Improved :ref:`load_endpoint_ref` endpoint to optionally accept a ZIP archive of an entire project with media files
  * Improved detection of installed AAC encoders
  * Improved speed of many endpoints (by reducing # of SQL queries and caching)
  * Reduced default video bitrate, for smaller files by default
  * Changed :ref:`title_endpoint_ref` endpoint to return the new file JSON (instead of a 302 redirect)
  * Allow OPTIONS method without authentication (for CORS)
  * Fixed webhooks for pending and failed exports
  * Fixed UTF-8 encoding error with unicode fonts (also added Noto fonts, including Japanese font)
  * Maintain original_id when /load/ endpoint is used
  * Added new unit tests for more coverage of API endpoints
  * Updated documentation with new endpoints

- **1.0.8** - Updated libopenshot version (fixed volume keyframe regression), and misc library improvements / fixes
- **1.0.7** - Reverting to libfdk_aac for AAC support. New native S3 support (for File and Export objects). Duplicate files on PUT or PATCH bug fixed. Improved file-system clean-up. Also improved docs with new S3 examples, and added upgrade instructions and release notes.
- **1.0.6** - Improved Audio Support (AAC), Better Memory Management, Misc Bug Fixes
- **1.0.5** - Stability Improvements, New Presets, Improved Docs
- **1.0.4** - Improved Webhooks, Improved Docs, Improved Logging, Misc Bug fixes
- **1.0.3** - Title Endpoints, Improved Docs, Misc Bug fixes
- **1.0.2** - Improved Performance, Improved Stability
- **1.0.1** - Stability Improvements, Misc Bug Fixes
- **1.0.0** - Initial Release of OpenShot Cloud API