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 // Copyright (c) 2008-2019 OpenShot Studios, LLC
10 //
11 // SPDX-License-Identifier: LGPL-3.0-or-later
12 
13 #ifndef OPENSHOT_CHUNK_READER_H
14 #define OPENSHOT_CHUNK_READER_H
15 
16 #include "ReaderBase.h"
17 #include <string>
18 #include <memory>
19 
20 #include "Frame.h"
21 #include "Json.h"
22 #include "CacheMemory.h"
23 
24 namespace openshot
25 {
26 
27  /**
28  * @brief This struct holds the location of a frame within a chunk.
29  *
30  * Chunks are small video files, which typically contain a few seconds of video each.
31  * Locating a frame among these small video files is accomplished by using
32  * this struct.
33  */
35  {
36  int64_t number; ///< The chunk number
37  int64_t frame; ///< The frame number
38  };
39 
40  /**
41  * @brief This enumeration allows the user to choose which version
42  * of the chunk they would like (low, medium, or high quality).
43  *
44  * Since chunks contain multiple video streams, this version enumeration
45  * allows the user to choose which version of the chunk they would like.
46  * For example, if you want a small version with reduced quality, you can
47  * choose the THUMBNAIL version. This is used on the ChunkReader
48  * constructor.
49  */
51  {
52  THUMBNAIL, ///< The lowest quality stream contained in this chunk file
53  PREVIEW, ///< The medium quality stream contained in this chunk file
54  FINAL ///< The highest quality stream contained in this chunk file
55  };
56 
57  /**
58  * @brief This class reads a special chunk-formatted file, which can be easily
59  * shared in a distributed environment.
60  *
61  * It stores the video in small "chunks", which are really just short video clips,
62  * a few seconds each. A ChunkReader only needs the part of the chunk that contains
63  * the frames it is looking for. For example, if you only need the end of a video,
64  * only the last few chunks might be needed to successfully access those openshot::Frame objects.
65  *
66  * \code
67  * // This example demonstrates how to read a chunk folder and access frame objects inside it.
68  * ChunkReader r("/home/jonathan/apps/chunks/chunk1/", FINAL); // Load highest quality version of this chunk file
69  * r.DisplayInfo(); // Display all known details about this chunk file
70  * r.Open(); // Open the reader
71  *
72  * // Access frame 1
73  * r.GetFrame(1)->Display();
74  *
75  * // Close the reader
76  * r.Close();
77  * \endcode
78  */
79  class ChunkReader : public ReaderBase
80  {
81  private:
82  std::string path;
83  bool is_open;
84  int64_t chunk_size;
85  openshot::ReaderBase *local_reader;
86  ChunkLocation previous_location;
87  ChunkVersion version;
88  std::shared_ptr<openshot::Frame> last_frame;
89 
90  /// Check if folder path existing
91  bool does_folder_exist(std::string path);
92 
93  /// Find the location of a frame in a chunk
94  ChunkLocation find_chunk_frame(int64_t requested_frame);
95 
96  /// get a formatted path of a specific chunk
97  std::string get_chunk_path(int64_t chunk_number, std::string folder, std::string extension);
98 
99  /// Load JSON meta data about this chunk folder
100  void load_json();
101 
102  public:
103 
104  /// @brief Constructor for ChunkReader. This automatically opens the chunk file or folder and loads
105  /// frame 1, or it throws one of the following exceptions.
106  /// @param path The folder path / location of a chunk (chunks are stored as folders)
107  /// @param chunk_version Choose the video version / quality (THUMBNAIL, PREVIEW, or FINAL)
108  ChunkReader(std::string path, ChunkVersion chunk_version);
109 
110  /// Close the reader
111  void Close() override;
112 
113  /// @brief Get the chunk size (number of frames to write in each chunk)
114  /// @returns The number of frames in this chunk
115  int64_t GetChunkSize() { return chunk_size; };
116 
117  /// @brief Set the chunk size (number of frames to write in each chunk)
118  /// @param new_size The number of frames per chunk
119  void SetChunkSize(int64_t new_size) { chunk_size = new_size; };
120 
121  /// Get the cache object used by this reader (always return NULL for this reader)
122  openshot::CacheMemory* GetCache() override { return NULL; };
123 
124  /// @brief Get an openshot::Frame object for a specific frame number of this reader.
125  /// @returns The requested frame (containing the image and audio)
126  /// @param requested_frame The frame number you want to retrieve
127  std::shared_ptr<openshot::Frame> GetFrame(int64_t requested_frame) override;
128 
129  /// Determine if reader is open or closed
130  bool IsOpen() override { return is_open; };
131 
132  /// Return the type name of the class
133  std::string Name() override { return "ChunkReader"; };
134 
135  // Get and Set JSON methods
136  std::string Json() const override; ///< Generate JSON string of this object
137  void SetJson(const std::string value) override; ///< Load JSON string into this object
138  Json::Value JsonValue() const override; ///< Generate Json::Value for this object
139  void SetJsonValue(const Json::Value root) override; ///< Load Json::Value into this object
140 
141  /// Open the reader. This is required before you can access frames or data from the reader.
142  void Open() override;
143  };
144 
145 }
146 
147 #endif
This class reads a special chunk-formatted file, which can be easily shared in a distributed environm...
Definition: ChunkReader.h:79
Header file for ReaderBase class.
The lowest quality stream contained in this chunk file.
Definition: ChunkReader.h:52
This abstract class is the base class, used by all readers in libopenshot.
Definition: ReaderBase.h:77
Header file for CacheMemory class.
The highest quality stream contained in this chunk file.
Definition: ChunkReader.h:54
Header file for Frame class.
The medium quality stream contained in this chunk file.
Definition: ChunkReader.h:53
Header file for JSON class.
void SetChunkSize(int64_t new_size)
Set the chunk size (number of frames to write in each chunk)
Definition: ChunkReader.h:119
int64_t number
The chunk number.
Definition: ChunkReader.h:36
ChunkVersion
This enumeration allows the user to choose which version of the chunk they would like (low...
Definition: ChunkReader.h:50
std::string Name() override
Return the type name of the class.
Definition: ChunkReader.h:133
int64_t GetChunkSize()
Get the chunk size (number of frames to write in each chunk)
Definition: ChunkReader.h:115
This namespace is the default namespace for all code in the openshot library.
Definition: Compressor.h:28
openshot::CacheMemory * GetCache() override
Get the cache object used by this reader (always return NULL for this reader)
Definition: ChunkReader.h:122
int64_t frame
The frame number.
Definition: ChunkReader.h:37
This struct holds the location of a frame within a chunk.
Definition: ChunkReader.h:34
This class is a memory-based cache manager for Frame objects.
Definition: CacheMemory.h:32
bool IsOpen() override
Determine if reader is open or closed.
Definition: ChunkReader.h:130