@mainpage libdcp
-libdcp is a small library to create Digital Cinema Packages (DCPs) from JPEG2000 and WAV files.
+libdcp is a small library to create and read Digital Cinema Packages (DCPs) from JPEG2000 and WAV files.
Most of the hard work is done by a (slightly patched) version of asdcplib (http://www.cinecert.com/asdcplib/)
which is included in the source distribution for libdcp.
libdcp is distributed under the GNU GPL.
-Typical use might be:
+Creating DCPs
+--
+
+Typical use for creating DCPs might be:
@code
#include <libdcp/dcp.h>
using namespace std;
If you want to report progress for long jobs (add_picture_asset() can
take a long time, in particular, as it must do a lot of disk I/O for
large DCPs), connect to the libdcp::DCP::Progress signal and report its parameter
-to the user (it will range between 0 for 0% and 1 for 100%).
+to the user (it will range between 0 for 0% and 1 for 100%) using something like
+
+@code
+void
+report (float p)
+{
+ cout << "We are " << int (p * 100) << "% done.\n";
+}
+
+dcp.Progress.connect (sigc::ptr_fun (&report));
+@endcode
If you can generate content paths algorithmically, you may prefer to do something
like this:
@endcode
+Reading existing DCPs
+--
+
+Alternatively libdcp can be used to read existing DCPs and examine their content. You
+might do
+
+@code
+#include <libdcp/dcp.h>
+using namespace std;
+
+libdcp::DCP dcp ("some-DCP-directory");
+@endcode
+
+libdcp will look at the XML files that make up the DCP and find its assets. You can then
+do things like
+
+@code
+boost::shared_ptr<libdcp::PictureAsset> p = dcp.picture_asset ();
+boost::shared_ptr<libdcp::RGBAFrame> f = p->get_frame(42)->rgba_frame ();
+uint8_t* data = f->data ();
+int size = f->size ();
+@endcode
+
+This will extract the image of frame 42 from the DCP and make its RGBA data available
+for examination.
+
+Audio data is accessed in chunks equal in length to the duration of a video frame. To
+get the audio that accompanies frame 66, you can do
+
+@code
+boost::shared_ptr<libdcp::SoundAsset> s = dcp.sound_asset ();
+cout << "Sound has " << s->channels() << " channels at " << s->sampling_rate() << "Hz\n";
+boost::shared_ptr<libdcp::SoundFrame> f = s->get_frame(66);
+uint8_t* data = f->data ();
+int size = f->size ();
+@endcode
+
+The returned data is interleaved 24-bit samples, so that
+
+@code
+int left = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int right = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int centre = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int lfe = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int ls = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int rs = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+@endcode
+
+would obtain the first sample from each of the 6 channels for that frame.
+
+Subtitles can be read using code like
+
+@code
+boost::shared_ptr<SubtitleAsset> s = dcp.subtitle_asset ();
+list<boost::shared_ptr<libdcp::Text> > texts = s->subtitles_at (libdcp::Time (0, 3, 2, 5));
+@endcode
+
+This returns the subtitles that should be shown at 3 minutes, 2
+seconds, 5 ticks (where 1 tick is 4ms) into the DCP.
+
*/
{
public:
/** Construct a DCP.
+ *
+ * This is for making a new DCP that you are going to add assets to.
+ *
* @param directory Directory to write files to.
* @param name Name.
* @param content_kind Content kind.
*/
DCP (std::string directory, std::string name, ContentKind content_kind, int fps, int length);
+ /** Construct a DCP object for an existing DCP.
+ *
+ * The DCP's XML metadata will be examined, and you can then look at the contents
+ * of the DCP.
+ *
+ * @param directory Existing DCP's directory.
+ */
DCP (std::string directory);
/** Add a sound asset.
*/
void write_xml () const;
+ /** @return the DCP's name, as will be presented on projector
+ * media servers and theatre management systems.
+ */
std::string name () const {
return _name;
}
+ /** @return the type of the content, used by media servers
+ * to categorise things (e.g. feature, trailer, etc.)
+ */
ContentKind content_kind () const {
return _content_kind;
}
+ /** @return the number of frames per second */
int frames_per_second () const {
return _fps;
}
+ /** @return the length in frames */
int length () const {
return _length;
}
+ /** @return the main picture asset, if one exists, otherwise 0 */
boost::shared_ptr<const PictureAsset> picture_asset () const;
+ /** @return the main sound asset, if one exists, otherwise 0 */
boost::shared_ptr<const SoundAsset> sound_asset () const;
+ /** @return the main subtitle asset, if one exists, otherwise 0 */
boost::shared_ptr<const SubtitleAsset> subtitle_asset () const;
+ /** Compare this DCP with another, according to various options.
+ * @param other DCP to compare this one to.
+ * @param options Options to define just what "equality" means.
+ * @return An empty list if the DCPs are equal; otherwise a list of messages
+ * which explain the ways in which they differ.
+ */
std::list<std::string> equals (DCP const & other, EqualityOptions options) const;
/** Emitted with a parameter between 0 and 1 to indicate progress
*/
+/** @file src/dcp_time.cc
+ * @brief A representation of time within a DCP.
+ */
+
#include <iostream>
#include <cmath>
#include "dcp_time.h"
*/
+/** @file src/dcp_time.h
+ * @brief A representation of time within a DCP.
+ */
+
#ifndef LIBDCP_TIME_H
#define LIBDCP_TIME_H
namespace libdcp {
+/** @class Time
+ * @brief A representation of time within a DCP.
+ */
+
class Time
{
public:
Time () : h (0), m (0), s (0), t (0) {}
+
+ /** Construct a Time from a frame index (starting from 0)
+ * and a frames per second count.
+ */
Time (int frame, int frames_per_second);
+
Time (int h_, int m_, int s_, int t_)
: h (h_)
, m (m_)
, t (t_)
{}
- int h;
- int m;
- int s;
- int t;
+ int h; ///< hours
+ int m; ///< minutes
+ int s; ///< seconds
+ int t; ///< `ticks', where 1 tick is 4 milliseconds
};
extern bool operator== (Time const & a, Time const & b);
public:
/** Construct an MXFAsset.
* @param directory Directory where MXF file is.
- * @param mxf_name Name of MXF file.
+ * @param file_name Name of MXF file.
* @param progress Signal to inform of progress.
* @param fps Frames per second.
* @param length Length in frames.
*/
- MXFAsset (std::string directory, std::string mxf_path, sigc::signal1<void, float>* progress, int fps, int length);
+ MXFAsset (std::string directory, std::string file_name, sigc::signal1<void, float>* progress, int fps, int length);
virtual std::list<std::string> equals (boost::shared_ptr<const Asset> other, EqualityOptions opt) const;
projects / libdcp.git / commitdiff