|
| 1 | +// SPDX-License-Identifier: Apache-2.0 |
| 2 | +// Copyright Contributors to the OpenTimelineIO project |
| 3 | + |
| 4 | +#pragma once |
| 5 | + |
| 6 | +#include "opentimelineio/timeline.h" |
| 7 | + |
| 8 | +namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { |
| 9 | + |
| 10 | +namespace bundle { |
| 11 | + |
| 12 | +/// @brief The current otioz version. |
| 13 | +static std::string const otioz_version = "1.0.0"; |
| 14 | + |
| 15 | +/// @brief The current otiod version. |
| 16 | +static std::string const otiod_version = "1.0.0"; |
| 17 | + |
| 18 | +/// @brief The version file name in the bundle. |
| 19 | +static std::string const version_file = "version.txt"; |
| 20 | + |
| 21 | +/// @brief The OTIO file name in the bundle. |
| 22 | +static std::string const otio_file = "content.otio"; |
| 23 | + |
| 24 | +/// @brief The media directory name in the bundle. |
| 25 | +static std::string const media_dir = "media"; |
| 26 | + |
| 27 | +/// @brief This enumeration provides the bundle media reference policy. |
| 28 | +enum class MediaReferencePolicy |
| 29 | +{ |
| 30 | + ErrorIfNotFile, ///< Return an error if there are any non-file media references. |
| 31 | + MissingIfNotFile, ///< Replace non-file media references with missing references. |
| 32 | + AllMissing ///< Replace all media references with missing references. |
| 33 | +}; |
| 34 | + |
| 35 | +/// @brief Options for writing bundles. |
| 36 | +struct WriteOptions |
| 37 | +{ |
| 38 | + /// @brief The parent path is used to locate media with relative paths. If |
| 39 | + /// parent path is empty, paths are relative to the current working directory. |
| 40 | + std::string parent_path; |
| 41 | + |
| 42 | + /// @brief The bundle media reference policy. |
| 43 | + MediaReferencePolicy media_policy = MediaReferencePolicy::ErrorIfNotFile; |
| 44 | + |
| 45 | + /// @todo Add comment. |
| 46 | + schema_version_map const* target_family_label_spec = nullptr; |
| 47 | + |
| 48 | + /// @brief The number of spaces to use for JSON indentation. |
| 49 | + int indent = 4; |
| 50 | +}; |
| 51 | + |
| 52 | +/// @brief Options for reading .otioz bundles. |
| 53 | +struct OtiozReadOptions |
| 54 | +{ |
| 55 | + /// @brief Extract the contents of the bundle to the given path. If the |
| 56 | + /// path is empty, the contents are not extracted, and only the timeline |
| 57 | + /// is read from the bundle. |
| 58 | + std::string extract_path; |
| 59 | +}; |
| 60 | + |
| 61 | +/// @brief Options for reading .otiod bundles. |
| 62 | +struct OtiodReadOptions |
| 63 | +{ |
| 64 | + /// @brief Use absolute paths for media references. |
| 65 | + bool absolute_media_reference_paths = false; |
| 66 | +}; |
| 67 | + |
| 68 | +/// @brief Get the total size (in bytes) of the media files that will be |
| 69 | +/// put into the bundle. |
| 70 | +size_t get_media_size( |
| 71 | + Timeline const* timeline, |
| 72 | + WriteOptions const& options = WriteOptions(), |
| 73 | + ErrorStatus* error_status = nullptr); |
| 74 | + |
| 75 | +/// @brief Write a timeline and it's referenced media to an .otioz bundle. |
| 76 | +/// |
| 77 | +/// Takes as input a timeline that has media references which are all |
| 78 | +/// ExternalReferences, with target_urls to files with unique basenames that are |
| 79 | +/// accessible through the file system. The timeline .otio file, a version file, |
| 80 | +/// and media references are bundled into a single zip file with the suffix |
| 81 | +/// .otioz. |
| 82 | +/// |
| 83 | +/// The timline .otio file and version file are compressed using the ZIP |
| 84 | +/// "deflate" mode. All media files are store uncompressed. |
| 85 | +/// |
| 86 | +/// Can error out if files are not locally referenced. or provide missing |
| 87 | +/// references. |
| 88 | +/// |
| 89 | +/// Note that .otioz files _always_ use the unix style path separator ('/'). |
| 90 | +/// This ensures that regardless of which platform a bundle was created on, it |
| 91 | +/// can be read on UNIX and Windows platforms. |
| 92 | +/// |
| 93 | +/// @param timeline The timeline to write. |
| 94 | +/// @param file_name The bundle file name. |
| 95 | +/// @param options The bundle options. |
| 96 | +/// @param error_status The error status. |
| 97 | +bool to_otioz( |
| 98 | + Timeline const* timeline, |
| 99 | + std::string const& file_name, |
| 100 | + WriteOptions const& options = WriteOptions(), |
| 101 | + ErrorStatus* error_status = nullptr); |
| 102 | + |
| 103 | +/// @brief Read a timeline from an .otioz bundle. |
| 104 | +/// |
| 105 | +/// @param file_name The bundle file name. |
| 106 | +/// @param output_dir The directory where the bundle will be extracted. |
| 107 | +/// @param error_status The error status. |
| 108 | +Timeline* from_otioz( |
| 109 | + std::string const& file_name, |
| 110 | + OtiozReadOptions const& options = OtiozReadOptions(), |
| 111 | + ErrorStatus* error_status = nullptr); |
| 112 | + |
| 113 | +/// @brief Write a timeline and it's referenced media to an .otiod bundle. |
| 114 | +/// |
| 115 | +/// Takes as input a timeline that has media references which are all |
| 116 | +/// ExternalReferences, with target_urls to files with unique basenames that are |
| 117 | +/// accessible through the file system. The timeline .otio file, a version file, |
| 118 | +/// and media references are bundled into a single directory named with a |
| 119 | +/// suffix of .otiod. |
| 120 | +/// |
| 121 | +/// @param timeline The timeline to write. |
| 122 | +/// @param file_name The bundle file name. |
| 123 | +/// @param options The bundle options. |
| 124 | +/// @param error_status The error status. |
| 125 | +bool to_otiod( |
| 126 | + Timeline const* timeline, |
| 127 | + std::string const& file_name, |
| 128 | + WriteOptions const& options = WriteOptions(), |
| 129 | + ErrorStatus* error_status = nullptr); |
| 130 | + |
| 131 | +/// @brief Read a timeline from an .otiod bundle. |
| 132 | +/// |
| 133 | +/// @param file_name The bundle file name. |
| 134 | +/// @param timeline_file_name Returns the timeline file name. |
| 135 | +/// @param error_status The error status. |
| 136 | +Timeline* from_otiod( |
| 137 | + std::string const& file_name, |
| 138 | + OtiodReadOptions const& options = OtiodReadOptions(), |
| 139 | + ErrorStatus* error_status = nullptr); |
| 140 | + |
| 141 | +} // namespace bundle |
| 142 | +}} // namespace opentimelineio::OPENTIMELINEIO_VERSION |
0 commit comments