Home

Getting Started

Before you attempt to use this library, you will need to have a solid understanding of the CWR file format. CWR is a flat text file, where the first 3 characters of each line specify what type of data is contained in that line. Before making use of this library, you should read both the Functional Specifications and the CWR User Manual:

Functional Specifications for CWR 2.2:
http://members.cisac.org/CisacPortal/consulterDocument.do?id=29541

CWR User Manual:
http://members.cisac.org/CisacPortal/consulterDocument.do?id=22272

---

Basic logic for creating a CWR file from song and recording metadata:

1. Create a new instance of the WorksRegistration object using WorksRegistration():

$cwr = new WorksRegistration($submitter_code, $submitter_ipi);

2. Add recordings using addTrack() and addRelease():

	foreach($tracks_releases as $t) if(!empty($t['ISRC'])) $cwr->addTrack($t);
	foreach($releases as $r) $cwr->addRelease($r);

3. Add songs using NewWork():

	$cwr->NewWork($song);

4. Add song splits and collection rights (by territory) using NewShare() and addTerritory():

	foreach($shares as $share)
	{
		$cwr->NewShare($share);
		$cwr->addTerritory(2136, array('Indicator' => 'I', 'PR_Collection_Share' => 50.00)); // Include "World" for this shareholder
		$cwr->addTerritory(840, array('Indicator' => 'E'));  // Exclude "United States" for this shareholder
	}

5. Add existing society registration numbers using addXRef():

	$cwr->addXRef(array( 
		'Organisation_Code'	=> 101, // This work has an existing registration ID at SOCAN
		'Identifier'		=> 12345678,
		'Identifier_Type'	=> 'W',
		'Validity'		=> 'Y' // For example purposes - this is not a real ID number!
		));

6. Add song shareholder details using addShareholder():

	foreach($shareholders as $shareholder)
		if(!$cwr->addShareholder($shareholder)) printf("%s\n", $cwr->LastMsg());

7. Create CWR file data using WriteCWR():

	$cwr->WriteCWR();
	file_put_contents($cwr->cwr_filename(), $cwr->CWR_File_Contents);

---

Basic logic to import works from a CWR file:

1. Create a new instance of the WorksRegistration object using WorksRegistration():

	$cwr = new WorksRegistration($submitter_code, $submitter_ipi);

2. Load the CWR file contents and parse it using ReadCWR():

	$cwr->CWR_File_Contents = file_get_contents("CW170024088_APO.V21");
	$cwr->ReadCWR();

3. Loop through the resulting songs using NextWork() and getWorkDetails():

	$cwr->CurrentWork = 0;
	while($cwr->NextWork())
	{
		$work = $cwr->getWorkDetails();
		if(!$work) printf("No work returned!\n");

		printf("\nWork:\n%s", $work['Title']);

4. The percentage of a work controlled can be calculated using percentageControlled():

		printf(" - This work is %02.2f%% controlled by the submitter.\n", $cwr->percentageControlled());

5. Loop through all of a song's shares using NextShare() and getShareDetails():

		$cwr->CurrentShare = 0;
		while($cwr->NextShare()) 
		{
			$shareholder = $cwr->getShareDetails();
			$ipi =& $shareholder['IPI'];

6. Lookup the details of each shareholder by referencing the Shareholders array:

			$shareholder['Name'] = $cwr->Shareholders[$ipi]['Name']." ".$cwr->Shareholders[$ipi]['First_Name'];
			printf("\nShareholder:\n%s (%d) - %0.2f%% / %0.2f%%\n", $shareholder['Name'], $shareholder['IPI'], $shareholder['PR_Ownership_Share'], $shareholder['MR_Ownership_Share']);

7. Collection rights for the current share can be found in the TIS records specified in the CWR file using getTISentries():

			$tis_entries = $cwr->getTISentries();

8. Collection rights can also be determined for every individual ISO country code by using getCollectionValues():

			if($collection_shares = $cwr->getCollectionValues())
			{
				printf("Collection rights in %d territories - derived from %s TIS statement(s):\n", count($collection_shares), count($tis_entries));
				foreach($tis_entries as $tis) printf("TIS %04d (%s): %s\n", $tis['TIS-N'], $tis['Indicator'], $tis['Name']);
				printf("%s\n\n", implode(", ", array_keys($collection_shares)));			
			}
			else printf("No collection rights defined.\n");
		}
	}

---

Function arguments to be supplied as arrays:

Array elements for NewWork():

(
	'Title'					=> Work title
	'Lang'					=> Language code
	'Work_ID'				=> Submitter's Work ID number
	'ISWC'					=> ISWC, if known
	'Copyright_Date'			=> Copyright date
	'Copyright_Number'			=> Copyright number
	'Musical_Work_Distribution_Category'	=> JAZ, POP, SER, or UNC
	'Duration'				=> Duration - can be either HHMMSS or HH:MM:SS
	'Recorded_Flag'				=> Y or N, indicates whether this work has been recorded
	'Text_Music_Relationship'		=> MUS, MTX or TXT
	'Composite_Type'			=> can be blank, otherwise COS, MED, POT, or UCO
	'Version_Type'				=> MOD or ORI
	'Music_Arrangement'			=> NEW, ARR, ADM, UNS or ORI
	'Lyric_Adaptation'			=> NEW, MOD, NON, ORI, REP, ADL, UNS or TRA
	'Contact_Name'				=> not currently used
	'Contact_ID'				=> not currently used
	'CWR_Work_Type'				=> TA, AC, AR, AL, AM, BD, BL, CD, CL, CC, CT, DN, FM, FK, BG, SG, JZ, JG, LN, LA, NA, OP, PK, PP, RP, RK, RB, SD or SY
	'Grand_Rights_Ind'			=> Y or N: Grand Rights indicator
	'Composite_Component_Count'		=> Composite component count
)

Array elements for NewShare():

(
	'IPI'			=> The shareholder's IPI number, or a temporary ID number <100000000 if the IPI is unknown
	'Role'			=> AD, AR, A, C, CA, SR, SA, TR, PA, AQ, AM, PA, E, ES, or SE
	'PR_Ownership_Share'	=> floating point number
	'MR_Ownership_Share'	=> floating point number
	'SR_Ownership_Share'	=> floating point number
	'Link'			=> integer that identifies the chain of title.  There can only be one publisher on a chain of title.
	'coPublisher'		=> integer that identifies the main chain of title if this is a co-publisher on a separate chain.
)

Array elements for addShareholder():

(
	'IPI'		=> IPI of the shareholder, or a temporary ID number <100000000 if the IPI is unknown
	'Name'		=> Writer's last name, or the name of the music publisher
	'First_Name'	=> Writer's first name
	'Controlled'	=> Y or N indicates whether or not this is a controlled shareholder
	'PRO'		=> integer identifying the shareholder's PRO affiliation (from the CISAC lookup tables)
	'US_Rep'	=> A, B, S (ASCAP, BMI, SESAC)
	'MRO'		=> integer identifying the shareholder's MRO affiliation (from the CISAC lookup tables)
	'SRO'		=> integer identifying the shareholder's SRO affiliation (from the CISAC lookup tables)
)

Array elements for addXRef():

(
	'Organisation_Code'	=> the CISAC society ID for the relevant organization
	'Identifier'		=> The organization's reference ID 
	'Identifier_Type'	=> W, R, P or V
	'Validity'		=> Y, N or U
)

Array elements for addTrack():

(
	'Track_ID'	=> internal Track ID reference
	'Duration'	=> track duration - can be either HHMMSS or HH:MM:SS
	'Artist_Name'	=> Artist name
	'Title'		=> Track title
	'Version'	=> Track version (e.g. "remix", etc.)
	'Label_Name'	=> Name of record label
)

Array elements for addRelease():

(
	'UPC'		=> UPC of release
	'Title'		=> Title of release
	'Label'		=> Name of record label
	'Cat_No'	=> Release catalogue number
	'Media_type'	=> BIEM/CISAC Media Type (from lookup table) 
	'Release_Date'	=> Release date - can be formatted as either YYYYMMDD or YYYY-MM-DD
)