@mainpage libdcp
-libdcp is a small library to create Digital Cinema Packages (DCPs) from JPEG2000 and WAV files.
+libdcp is a library to create Digital Cinema Packages (DCPs) from JPEG2000 and WAV files, and also to
+read and process existing DCPs.
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:
-@code
-#include <libdcp/dcp.h>
-using namespace std;
+Creating DCPs
+--
-libdcp::DCP dcp ("My Film DCP", "My Film", libdcp::DCP::FEATURE, 24, 50000);
+An example of DCP creation is given in examples/make_dcp.cc.
-vector<string> j2k_files;
-j2k_files.push_back ("1.j2c");
-...
-j2k_files.push_back ("50000.j2c");
+Reading existing DCPs
+--
-// These images are 1998x1080 pixels (DCI Flat)
-dcp.add_picture_asset (j2k_files, 1998, 1080);
+libdcp can be used to read existing DCPs and examine their content. You might do
-vector<string> wav_files;
-wav_files.push_back ("L.wav");
-wav_files.push_back ("R.wav");
-wav_files.push_back ("C.wav");
-wav_files.push_back ("Lfe.wav");
-wav_files.push_back ("Ls.wav");
-wav_files.push_back ("Rs.wav");
-dcp.add_sound_asset (wav_files);
-
-dcp.write_xml ();
+@code
+#include <libdcp/dcp.h>
+using namespace std;
+libdcp::DCP dcp ("some-DCP-directory");
@endcode
-This will create a DCP at 24 frames per second with 50000 frames, writing
-data to a directory "My Film DCP", naming the DCP "My Film" and marking
-as a Feature. We then add the picture and sound files (which creates
-MXF files inside the DCP directory) and then write the required XML files.
-
-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%).
-
-If you can generate content paths algorithmically, you may prefer to do something
-like this:
+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<Reel> reel = dcp.reels.front ();
+boost::shared_ptr<libdcp::PictureAsset> p = reel->main_picture ();
+boost::shared_ptr<libdcp::MonoPictureAsset> mp = boost::dynamic_pointer_cast<libdcp::MonoPictureAsset> (p);
+boost::shared_ptr<libdcp::ARGBFrame> f = mp->get_frame(42)->argb_frame ();
+uint8_t* data = f->data ();
+int size = f->size ();
+@endcode
+
+This will extract the image of frame 42 from the first reel of the DCP and make its ARGB data available
+for examination. We have to do a <code>dynamic_pointer_cast</code> from <code>libdcp::PictureAsset</code>
+to <code>libdcp::MonoPictureAsset</code>, as the picture asset may be either 2D (monoscopic) or 3D (stereoscopic).
-string
-j2k_path (int frame)
-{
- stringstream s;
- s << "my_j2ks/" << frame << ".j2c"
- return s.str ();
-}
+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
-string
-wav_path (libdcp::Channel channel)
-{
- switch (channel) {
- case LEFT:
- return "left.wav";
- case RIGHT:
- return "right.wav";
- }
+@code
+boost::shared_ptr<libdcp::SoundAsset> s = reel->main_sound ();
+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
- return "";
-}
+The returned data are 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
-// Our images are 1998x1080 (DCI Flat)
-dcp.add_picture_asset (sigc::ptr_fun (&j2k_path), 1998, 1080);
-// We have two sound channels
-dcp.add_sound_asset (sigc::ptr_fun (&wav_path), 2);
+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.
+
*/
projects / libdcp.git / blobdiff