OpenShot Library | libopenshot 0.2.7
ChunkReader.h
Go to the documentation of this file.
1/**
2 * @file
3 * @brief Header file for ChunkReader class
4 * @author Jonathan Thomas <jonathan@openshot.org>
5 *
6 * @ref License
7 */
8
9/* LICENSE
10 *
11 * Copyright (c) 2008-2019 OpenShot Studios, LLC
12 * <http://www.openshotstudios.com/>. This file is part of
13 * OpenShot Library (libopenshot), an open-source project dedicated to
14 * delivering high quality video editing and animation solutions to the
15 * world. For more information visit <http://www.openshot.org/>.
16 *
17 * OpenShot Library (libopenshot) is free software: you can redistribute it
18 * and/or modify it under the terms of the GNU Lesser General Public License
19 * as published by the Free Software Foundation, either version 3 of the
20 * License, or (at your option) any later version.
21 *
22 * OpenShot Library (libopenshot) is distributed in the hope that it will be
23 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 * GNU Lesser General Public License for more details.
26 *
27 * You should have received a copy of the GNU Lesser General Public License
28 * along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
29 */
30
31#ifndef OPENSHOT_CHUNK_READER_H
32#define OPENSHOT_CHUNK_READER_H
33
34#include "ReaderBase.h"
35#include <string>
36#include <memory>
37
38#include "Frame.h"
39#include "Json.h"
40#include "CacheMemory.h"
41
42namespace openshot
43{
44
45 /**
46 * @brief This struct holds the location of a frame within a chunk.
47 *
48 * Chunks are small video files, which typically contain a few seconds of video each.
49 * Locating a frame among these small video files is accomplished by using
50 * this struct.
51 */
53 {
54 int64_t number; ///< The chunk number
55 int64_t frame; ///< The frame number
56 };
57
58 /**
59 * @brief This enumeration allows the user to choose which version
60 * of the chunk they would like (low, medium, or high quality).
61 *
62 * Since chunks contain multiple video streams, this version enumeration
63 * allows the user to choose which version of the chunk they would like.
64 * For example, if you want a small version with reduced quality, you can
65 * choose the THUMBNAIL version. This is used on the ChunkReader
66 * constructor.
67 */
69 {
70 THUMBNAIL, ///< The lowest quality stream contained in this chunk file
71 PREVIEW, ///< The medium quality stream contained in this chunk file
72 FINAL ///< The highest quality stream contained in this chunk file
73 };
74
75 /**
76 * @brief This class reads a special chunk-formatted file, which can be easily
77 * shared in a distributed environment.
78 *
79 * It stores the video in small "chunks", which are really just short video clips,
80 * a few seconds each. A ChunkReader only needs the part of the chunk that contains
81 * the frames it is looking for. For example, if you only need the end of a video,
82 * only the last few chunks might be needed to successfully access those openshot::Frame objects.
83 *
84 * \code
85 * // This example demonstrates how to read a chunk folder and access frame objects inside it.
86 * ChunkReader r("/home/jonathan/apps/chunks/chunk1/", FINAL); // Load highest quality version of this chunk file
87 * r.DisplayInfo(); // Display all known details about this chunk file
88 * r.Open(); // Open the reader
89 *
90 * // Access frame 1
91 * r.GetFrame(1)->Display();
92 *
93 * // Close the reader
94 * r.Close();
95 * \endcode
96 */
97 class ChunkReader : public ReaderBase
98 {
99 private:
100 std::string path;
101 bool is_open;
102 int64_t chunk_size;
103 openshot::ReaderBase *local_reader;
104 ChunkLocation previous_location;
105 ChunkVersion version;
106 std::shared_ptr<openshot::Frame> last_frame;
107
108 /// Check if folder path existing
109 bool does_folder_exist(std::string path);
110
111 /// Find the location of a frame in a chunk
112 ChunkLocation find_chunk_frame(int64_t requested_frame);
113
114 /// get a formatted path of a specific chunk
115 std::string get_chunk_path(int64_t chunk_number, std::string folder, std::string extension);
116
117 /// Load JSON meta data about this chunk folder
118 void load_json();
119
120 public:
121
122 /// @brief Constructor for ChunkReader. This automatically opens the chunk file or folder and loads
123 /// frame 1, or it throws one of the following exceptions.
124 /// @param path The folder path / location of a chunk (chunks are stored as folders)
125 /// @param chunk_version Choose the video version / quality (THUMBNAIL, PREVIEW, or FINAL)
126 ChunkReader(std::string path, ChunkVersion chunk_version);
127
128 /// Close the reader
129 void Close() override;
130
131 /// @brief Get the chunk size (number of frames to write in each chunk)
132 /// @returns The number of frames in this chunk
133 int64_t GetChunkSize() { return chunk_size; };
134
135 /// @brief Set the chunk size (number of frames to write in each chunk)
136 /// @param new_size The number of frames per chunk
137 void SetChunkSize(int64_t new_size) { chunk_size = new_size; };
138
139 /// Get the cache object used by this reader (always return NULL for this reader)
140 openshot::CacheMemory* GetCache() override { return NULL; };
141
142 /// @brief Get an openshot::Frame object for a specific frame number of this reader.
143 /// @returns The requested frame (containing the image and audio)
144 /// @param requested_frame The frame number you want to retrieve
145 std::shared_ptr<openshot::Frame> GetFrame(int64_t requested_frame) override;
146
147 /// Determine if reader is open or closed
148 bool IsOpen() override { return is_open; };
149
150 /// Return the type name of the class
151 std::string Name() override { return "ChunkReader"; };
152
153 // Get and Set JSON methods
154 std::string Json() const override; ///< Generate JSON string of this object
155 void SetJson(const std::string value) override; ///< Load JSON string into this object
156 Json::Value JsonValue() const override; ///< Generate Json::Value for this object
157 void SetJsonValue(const Json::Value root) override; ///< Load Json::Value into this object
158
159 /// Open the reader. This is required before you can access frames or data from the reader.
160 void Open() override;
161 };
162
163}
164
165#endif
Header file for CacheMemory class.
Header file for Frame class.
Header file for JSON class.
Header file for ReaderBase class.
This class is a memory-based cache manager for Frame objects.
Definition: CacheMemory.h:50
This class reads a special chunk-formatted file, which can be easily shared in a distributed environm...
Definition: ChunkReader.h:98
std::string Json() const override
Generate JSON string of this object.
void Close() override
Close the reader.
bool IsOpen() override
Determine if reader is open or closed.
Definition: ChunkReader.h:148
void Open() override
Open the reader. This is required before you can access frames or data from the reader.
Json::Value JsonValue() const override
Generate Json::Value for this object.
ChunkReader(std::string path, ChunkVersion chunk_version)
Constructor for ChunkReader. This automatically opens the chunk file or folder and loads frame 1,...
Definition: ChunkReader.cpp:39
std::shared_ptr< openshot::Frame > GetFrame(int64_t requested_frame) override
Get an openshot::Frame object for a specific frame number of this reader.
void SetJsonValue(const Json::Value root) override
Load Json::Value into this object.
int64_t GetChunkSize()
Get the chunk size (number of frames to write in each chunk)
Definition: ChunkReader.h:133
openshot::CacheMemory * GetCache() override
Get the cache object used by this reader (always return NULL for this reader)
Definition: ChunkReader.h:140
void SetJson(const std::string value) override
Load JSON string into this object.
std::string Name() override
Return the type name of the class.
Definition: ChunkReader.h:151
void SetChunkSize(int64_t new_size)
Set the chunk size (number of frames to write in each chunk)
Definition: ChunkReader.h:137
This abstract class is the base class, used by all readers in libopenshot.
Definition: ReaderBase.h:98
This namespace is the default namespace for all code in the openshot library.
Definition: Compressor.h:47
ChunkVersion
This enumeration allows the user to choose which version of the chunk they would like (low,...
Definition: ChunkReader.h:69
@ THUMBNAIL
The lowest quality stream contained in this chunk file.
Definition: ChunkReader.h:70
@ FINAL
The highest quality stream contained in this chunk file.
Definition: ChunkReader.h:72
@ PREVIEW
The medium quality stream contained in this chunk file.
Definition: ChunkReader.h:71
This struct holds the location of a frame within a chunk.
Definition: ChunkReader.h:53
int64_t number
The chunk number.
Definition: ChunkReader.h:54
int64_t frame
The frame number.
Definition: ChunkReader.h:55