Some comments; fix up a UUID I think.

11 files changed, 97 insertions, 84 deletions

diff --git a/run-tests.sh b/run-tests.sh
index a16806f7..701b25d6 100755
--- a/run-tests.sh
+++ b/run-tests.sh
@@ -1,5 +1,12 @@
 #!/bin/sh
 
+#
+# Runs our test suite, which builds a DCP.
+# The output is compared against the one
+# in test/ref/DCP, and an error is given
+# if anything is different.
+#
+
 LD_LIBRARY_PATH=build/src:build/asdcplib/src
 build/test/tests
 diff -ur build/test/foo test/ref/DCP
diff --git a/src/asset.cc b/src/asset.cc
index 4e3bb0e1..e2624712 100644
--- a/src/asset.cc
+++ b/src/asset.cc
@@ -44,6 +44,9 @@ Asset::Asset (string p, int fps, int len)
 	
 }
 
+/** Write details of the asset to a PKL stream.
+ *  @param s Stream.
+ */
 void
 Asset::write_to_pkl (ostream& s) const
 {
@@ -56,6 +59,9 @@ Asset::write_to_pkl (ostream& s) const
 	  << "    </Asset>\n";
 }
 
+/** Write details of the asset to a ASSETMAP stream.
+ *  @param s Stream.
+ */
 void
 Asset::write_to_assetmap (ostream& s) const
 {
@@ -72,6 +78,7 @@ Asset::write_to_assetmap (ostream& s) const
 	  << "    </Asset>\n";
 }
 
+/** Fill in a ADSCP::WriteInfo struct */
 void
 Asset::fill_writer_info (ASDCP::WriterInfo* writer_info) const
 {
@@ -80,5 +87,7 @@ Asset::fill_writer_info (ASDCP::WriterInfo* writer_info) const
 	writer_info->ProductName = Tags::instance()->product_name.c_str();
 
 	writer_info->LabelSetType = ASDCP::LS_MXF_SMPTE;
-	Kumu::GenRandomUUID (writer_info->AssetUUID);
+	unsigned int c;
+	Kumu::hex2bin (_uuid.c_str(), writer_info->AssetUUID, Kumu::UUID_Length, &c);
+	assert (c == Kumu::UUID_Length);
 }
diff --git a/src/asset.h b/src/asset.h
index ce742d11..fb701570 100644
--- a/src/asset.h
+++ b/src/asset.h
@@ -30,6 +30,7 @@ namespace ASDCP {
 namespace libdcp
 {
 
+/** Parent class for assets (picture / sound collections) */	
 class Asset
 {
 public:
@@ -39,15 +40,23 @@ public:
 	void write_to_pkl (std::ostream &) const;
 	void write_to_assetmap (std::ostream &) const;
 
+	/** Emitted with a parameter between 0 and 1 to indicate progress in constructing
+	 *  this asset.
+	 */
 	sigc::signal1<void, float> Progress;
 
 protected:
 	void fill_writer_info (ASDCP::WriterInfo *) const;
 
+	/** Path to our MXF file */
 	std::string _mxf_path;
+	/** Frames per second */
 	int _fps;
+	/** Length in frames */
 	int _length;
+	/** Our UUID */
 	std::string _uuid;
+	/** Digest of our MXF */
 	std::string _digest;
 };
 
diff --git a/src/dcp.cc b/src/dcp.cc
index 758e357b..b691d146 100644
--- a/src/dcp.cc
+++ b/src/dcp.cc
@@ -35,6 +35,10 @@ using namespace libdcp;
 
 /** Construct a DCP.
  *  @param d Directory to write files to.
+ *  @param n Name.
+ *  @param c Content type.
+ *  @param fps Frames per second.
+ *  @param length Length in frames.
  */
 DCP::DCP (string d, string n, ContentType c, int fps, int length)
 	: _directory (d)
@@ -45,6 +49,9 @@ DCP::DCP (string d, string n, ContentType c, int fps, int length)
 {
 }
 
+/** Add a sound asset.
+ *  @param files Pathnames of WAV files to use in the order Left, Right, Centre, Lfe (sub), Left surround, Right surround.
+ */
 void
 DCP::add_sound_asset (list<string> const & files)
 {
@@ -54,6 +61,9 @@ DCP::add_sound_asset (list<string> const & files)
 	_assets.push_back (shared_ptr<SoundAsset> (new SoundAsset (files, p.string(), _fps, _length)));
 }
 
+/** Add a picture asset.
+ *  @param files Pathnames of JPEG2000 files, in frame order.
+ */
 void
 DCP::add_picture_asset (list<string> const & files, int w, int h)
 {
@@ -168,6 +178,7 @@ DCP::write_pkl (string pkl_uuid, string cpl_uuid, string cpl_digest, int cpl_len
 	return p.string ();
 }
 
+/** Write the VOLINDEX file */
 void
 DCP::write_volindex () const
 {
@@ -182,6 +193,12 @@ DCP::write_volindex () const
 	   << "</VolumeIndex>\n";
 }
 
+/** Write the ASSETMAP file.
+ *  @param cpl_uuid UUID of our CPL.
+ *  @param cpl_length Length of our CPL in bytes.
+ *  @param pkl_uuid UUID of our PKL.
+ *  @param pkl_length Length of our PKL in bytes.
+ */
 void
 DCP::write_assetmap (string cpl_uuid, int cpl_length, string pkl_uuid, int pkl_length) const
 {
@@ -232,7 +249,9 @@ DCP::write_assetmap (string cpl_uuid, int cpl_length, string pkl_uuid, int pkl_l
 	   << "</AssetMap>\n";
 }
 
-
+/** @param t A content type.
+ *  @return A string representation suitable for use in a CPL.
+ */
 string
 DCP::content_type_string (ContentType t)
 {
diff --git a/src/dcp.h b/src/dcp.h
index 2c320451..6896267c 100644
--- a/src/dcp.h
+++ b/src/dcp.h
@@ -26,6 +26,7 @@ namespace libdcp
 
 class Asset;	
 
+/** A class to create a DCP */	
 class DCP
 {
 public:
@@ -59,11 +60,17 @@ private:
 
 	static std::string content_type_string (ContentType);
 
+	/** the directory that we are writing to */
 	std::string _directory;
+	/** the name of the DCP */
 	std::string _name;
+	/** the content type of the DCP */
 	ContentType _content_type;
+	/** frames per second */
 	int _fps;
+	/** length in frames */
 	int _length;
+	/** assets */
 	std::list<boost::shared_ptr<Asset> > _assets;
 };
 
diff --git a/test/ref/DCP/8e293965-f8ad-48c6-971d-261b01f65cdb_pkl.xml b/test/ref/DCP/8e293965-f8ad-48c6-971d-261b01f65cdb_pkl.xml
deleted file mode 100644
index 0e62ce07..00000000
--- a/test/ref/DCP/8e293965-f8ad-48c6-971d-261b01f65cdb_pkl.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<PackingList xmlns="http://www.smpte-ra.org/schemas/429-8/2007/PKL">
-  <Id>urn:uuid:8e293965-f8ad-48c6-971d-261b01f65cdb</Id>
-  <AnnotationText>A Test DCP</AnnotationText>
-  <IssueDate>2012-07-17T04:45:18+00:00</IssueDate>
-  <Issuer>OpenDCP 0.0.25</Issuer>
-  <Creator>OpenDCP 0.0.25</Creator>
-  <AssetList>
-    <Asset>
-      <Id>urn:uuid:81fb54df-e1bf-4647-8788-ea7ba154375b</Id>
-      <AnnotationText>video.mxf</AnnotationText>
-      <Hash>E2vhyxdJQhEzSQZdp31w84ZZpfk=</Hash>
-      <Size>26080</Size>
-      <Type>application/mxf</Type>
-    </Asset>
-    <Asset>
-      <Id>urn:uuid:c38bdd62-ce03-4988-8603-195f134207c7</Id>
-      <AnnotationText>audio.mxf</AnnotationText>
-      <Hash>9OVODrw+zTkSbkGduoQ30k3Kk6Y=</Hash>
-      <Size>305326</Size>
-      <Type>application/mxf</Type>
-    </Asset>
-    <Asset>
-      <Id>urn:uuid:df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb</Id>
-      <Hash>5E8Q9swcc2bBbFF3IEPNXfIP8gM=</Hash>
-      <Size>1526</Size>
-      <Type>text/xml</Type>
-    </Asset>
-  </AssetList>
-</PackingList>
diff --git a/test/ref/DCP/ASSETMAP.xml b/test/ref/DCP/ASSETMAP.xml
index edb62bda..b0168478 100644
--- a/test/ref/DCP/ASSETMAP.xml
+++ b/test/ref/DCP/ASSETMAP.xml
@@ -1,17 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <AssetMap xmlns="http://www.smpte-ra.org/schemas/429-9/2007/AM">
-  <Id>urn:uuid:18be072e-5a0f-44e1-b2eb-c8a52ae12789</Id>
+  <Id>urn:uuid:b135d5cf-d180-43d8-b0b3-7373737b73bf</Id>
   <Creator>OpenDCP 0.0.25</Creator>
   <VolumeCount>1</VolumeCount>
   <IssueDate>2012-07-17T04:45:18+00:00</IssueDate>
   <Issuer>OpenDCP 0.0.25</Issuer>
   <AssetList>
     <Asset>
-      <Id>urn:uuid:8e293965-f8ad-48c6-971d-261b01f65cdb</Id>
+      <Id>urn:uuid:df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb</Id>
       <PackingList>true</PackingList>
       <ChunkList>
         <Chunk>
-          <Path>8e293965-f8ad-48c6-971d-261b01f65cdb_pkl.xml</Path>
+          <Path>df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb_pkl.xml</Path>
           <VolumeIndex>1</VolumeIndex>
           <Offset>0</Offset>
           <Length>1049</Length>
@@ -19,10 +19,10 @@
       </ChunkList>
     </Asset>
     <Asset>
-      <Id>urn:uuid:df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb</Id>
+      <Id>urn:uuid:9892e944-5046-4dbb-af7c-f50742f62fc2</Id>
       <ChunkList>
         <Chunk>
-          <Path>df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb_cpl.xml</Path>
+          <Path>9892e944-5046-4dbb-af7c-f50742f62fc2_cpl.xml</Path>
           <VolumeIndex>1</VolumeIndex>
           <Offset>0</Offset>
           <Length>1526</Length>
@@ -41,7 +41,7 @@
       </ChunkList>
     </Asset>
     <Asset>
-      <Id>urn:uuid:c38bdd62-ce03-4988-8603-195f134207c7</Id>
+      <Id>urn:uuid:67b9341e-cadd-4dac-9d5c-f5a1d59f2d06</Id>
       <ChunkList>
         <Chunk>
           <Path>audio.mxf</Path>
diff --git a/test/ref/DCP/audio.mxf b/test/ref/DCP/audio.mxf
index 8910b6fb..52f92d21 100644
--- a/test/ref/DCP/audio.mxf
+++ b/test/ref/DCP/audio.mxf
diff --git a/test/ref/DCP/df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb_cpl.xml b/test/ref/DCP/df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb_cpl.xml
deleted file mode 100644
index bb8775fd..00000000
--- a/test/ref/DCP/df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb_cpl.xml
+++ /dev/null
@@ -1,39 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<CompositionPlaylist xmlns="http://www.smpte-ra.org/schemas/429-7/2006/CPL">
-  <Id>urn:uuid:df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb</Id>
-  <AnnotationText>A Test DCP</AnnotationText>
-  <IssueDate>2012-07-17T04:45:18+00:00</IssueDate>
-  <Creator>OpenDCP 0.0.25</Creator>
-  <ContentTitleText>A Test DCP</ContentTitleText>
-  <ContentKind>feature</ContentKind>
-  <ContentVersion>
-    <Id>urn:uri:df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb_2012-07-17T04:45:18+00:00</Id>
-    <LabelText>df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb_2012-07-17T04:45:18+00:00</LabelText>
-  </ContentVersion>
-  <RatingList/>
-  <ReelList>
-    <Reel>
-      <Id>urn:uuid:b135d5cf-d180-43d8-b0b3-7373737b73bf</Id>
-      <AssetList>
-        <MainPicture>
-          <Id>urn:uuid:81fb54df-e1bf-4647-8788-ea7ba154375b</Id>
-          <AnnotationText>video.mxf</AnnotationText>
-          <EditRate>24 1</EditRate>
-          <IntrinsicDuration>24</IntrinsicDuration>
-          <EntryPoint>0</EntryPoint>
-          <Duration>24</Duration>
-          <FrameRate>24 1</FrameRate>
-          <ScreenAspectRatio>32 32</ScreenAspectRatio>
-        </MainPicture>
-        <MainSound>
-          <Id>urn:uuid:c38bdd62-ce03-4988-8603-195f134207c7</Id>
-          <AnnotationText>audio.mxf</AnnotationText>
-          <EditRate>24 1</EditRate>
-          <IntrinsicDuration>24</IntrinsicDuration>
-          <EntryPoint>0</EntryPoint>
-          <Duration>24</Duration>
-        </MainSound>
-      </AssetList>
-    </Reel>
-  </ReelList>
-</CompositionPlaylist>
diff --git a/test/ref/DCP/video.mxf b/test/ref/DCP/video.mxf
index 645fb85a..70040fc3 100644
--- a/test/ref/DCP/video.mxf
+++ b/test/ref/DCP/video.mxf
diff --git a/test/ref/make.py b/test/ref/make.py
index 0b469e24..ac8ff155 100755
--- a/test/ref/make.py
+++ b/test/ref/make.py
@@ -1,23 +1,52 @@
 #!/usr/bin/python
 
+#
+# This slightly ridiculous script gets OpenDCP to generate
+# a DCP using out test reference data (in j2c/ and wav/)
+# and then adjusts its XML output to account for the fact
+# that OpenDCP will generate its own random UUIDs (and use
+# current timestamps).  We set UUIDs and timestamps back
+# to what our test suite will expect.
+#
+# The output of this script is checked into git, so
+# there's normally no need to run it.
+#
+# If you do run it, the XML should be right but the 
+# MXFs that OpenDCP generates will not be quite what
+# we expect, as they also contain random UUIDs.  I don't
+# think there's an easy way round that, so after running
+# this script you will need to check that the libdcp
+# test code generates correct MXFs (by verification on
+# a projector, probably), and then copy those MXFs into the
+# test/ref/DCP directory.
+#
+
 import os
 import sys
 import fileinput
 from lxml import etree
 
+# Namespaces for the various XML files
 assetmap_namespace = 'http://www.smpte-ra.org/schemas/429-9/2007/AM'
 cpl_namespace = 'http://www.smpte-ra.org/schemas/429-7/2006/CPL'
 pkl_namespace = 'http://www.smpte-ra.org/schemas/429-8/2007/PKL'
 
-wanted_cpl_id = 'df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb'
-wanted_pkl_id = '8e293965-f8ad-48c6-971d-261b01f65cdb'
-wanted_assetmap_id = '18be072e-5a0f-44e1-b2eb-c8a52ae12789'
+# The UUIDs of things that we want to put into the
+# OpenDCP-generated XML
+wanted_cpl_id = '9892e944-5046-4dbb-af7c-f50742f62fc2'
+wanted_pkl_id = 'df0e4141-13c3-4a7a-bef8-b5a04fcbc4bb'
+wanted_assetmap_id = 'b135d5cf-d180-43d8-b0b3-7373737b73bf'
 wanted_video_mxf_id = '81fb54df-e1bf-4647-8788-ea7ba154375b'
-wanted_audio_mxf_id = 'c38bdd62-ce03-4988-8603-195f134207c7'
-wanted_reel_id = 'b135d5cf-d180-43d8-b0b3-7373737b73bf'
-wanted_asset_hashes = ['E2vhyxdJQhEzSQZdp31w84ZZpfk=', '9OVODrw+zTkSbkGduoQ30k3Kk6Y=', '5E8Q9swcc2bBbFF3IEPNXfIP8gM=']
+wanted_audio_mxf_id = '67b9341e-cadd-4dac-9d5c-f5a1d59f2d06'
+wanted_reel_id = '379fa64c-ad71-46cf-bef7-b45624006610'
+
+# The hashes of the assets: first is the video MXF, second the audio MXF and third the CPL.
+wanted_asset_hashes = ['VB9LCTmiD9OLlw4SvrEWUm5d67Q=', 'HapNpn7MjiJLa1OHRI61Rx8N/is=', 'PbXuvpUOKccTLMxg/lEbaXvNCT4=']
+
+# The issue date that we want to use
 wanted_issue_date = '2012-07-17T04:45:18+00:00'
 
+# Get OpenDCP to make the DCP
 os.system('rm -rf DCP')
 os.mkdir('DCP')
 os.system('opendcp_mxf -i j2c -o DCP/video.mxf -r 24')
@@ -25,6 +54,7 @@ os.system('opendcp_mxf -i wav -o DCP/audio.mxf -r 24')
 os.system('opendcp_xml --reel DCP/video.mxf DCP/audio.mxf -k feature -t "A Test DCP" -a "A Test DCP"')
 os.system('mv *.xml DCP')
 
+# Find what IDs it used
 cpl_id = None
 pkl_id = None
 assetmap_id = None
@@ -39,6 +69,7 @@ for r, d, f in os.walk('DCP'):
         elif n.endswith('pkl.xml'):
             pkl_id = n[0:-8]
 
+# (along the way, rename the CPL/PKL files)
 os.rename('DCP/%s_cpl.xml' % cpl_id, 'DCP/%s_cpl.xml' % wanted_cpl_id)
 os.rename('DCP/%s_pkl.xml' % pkl_id, 'DCP/%s_pkl.xml' % wanted_pkl_id)
 
@@ -77,13 +108,13 @@ xml = etree.parse('DCP/%s_pkl.xml' % wanted_pkl_id)
 
 asset_list =   xml.getroot().find(pkl_name('AssetList'))
 asset_hashes = []
-print asset_list
 for a in asset_list.iter():
     if a.tag == "{%s}Hash" % pkl_namespace:
         asset_hashes.append(a.text)
 
 issue_date =    xml.getroot().find(pkl_name('IssueDate')).text
 
+# Now run through the XML files doing the replacements
 for r, d, f in os.walk('DCP'):
     for n in f:
         if n.endswith('.xml'):