listCuePoints() objects have always the same props

rochars · Jan 7, 2020 · 29aa6e6 · 29aa6e6
1 parent ebfdb8e
commit 29aa6e6
Show file tree

Hide file tree

Showing 11 changed files with 184 additions and 174 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,14 +1,33 @@
 # CHANGELOG
 
-## version 10.0.0 - (unreleased)
+## version 10.0.0 - 2020-01-07
 Better handling of cue points and regions.
 
-Features:
-- setCuePoint() now can create both cue points and regions
-
-API Changes:
-- listCuePoints() now returns a object with more information about each cue point
-- setCuePoint() param is now a object with the cue point data
+### API Changes:
+- *listCuePoints()* now returns a list of objects with more information about each cue point:
+```javascript
+[
+	{
+		position: 500, // the position in milliseconds
+		label: 'cue marker 1',
+		end: 1500, // the end position in milliseconds
+		dwName: 1,
+		dwPosition: 0,
+		fccChunk: 'data',
+		dwChunkStart: 0,
+		dwBlockStart: 0,
+		dwSampleOffset: 22050, // the position as a sample offset
+		dwSampleLength: 3646827, // the region length as a sample count
+		dwPurposeID: 544106354,
+		dwCountry: 0,
+		dwLanguage: 0,
+		dwDialect: 0,
+		dwCodePage: 0,
+	},
+	//...
+];
+```
+- *setCuePoint()* param is now a object with the cue point data:
 ```javascript
 // to create a cue point the position in milliseconds
 // is the only required attribute
@@ -20,8 +39,17 @@ wav.setCuePoint({position: 1500, label: 'some label'});
 // to create a cue region with a label:
 wav.setCuePoint({position: 1500, end: 2500, label: 'some label'});
 ```
+Objects that define regions can also define the following optional properties:
+- dwPurposeID
+- dwCountry
+- dwLanguage
+- dwDialect
+- dwCodePage
+
+### New Features:
+- setCuePoint() now can create both cue points and regions.
 
-Fixes:
+### Fixes:
 - Fix setCuePoint() bug that caused some labels to display the wrong text
 
 

diff --git a/README.md b/README.md
@@ -25,6 +25,7 @@ With **wavefile** you can:
 - Change the bit depth of the audio
 - Read and write RIFF tags
 - Set and delete cue points and their labels
+- Create regions in wav files
 - Encode/decode files as ADPCM, A-Law and μ-Law
 - Turn RIFF files to RIFX and RIFX to RIFF
 - Create or edit BWF metadata ("bext" chunk)
@@ -229,34 +230,67 @@ wav.deleteTag("ICMT");
 ```
 
 ### Add cue points to files
-You can create cue points using the **WaveFile.setCuePoint()** method. The method takes a object with the cue point data and creates a cue point in the corresponding position of the file. The only required attribute of the object is 'position', a number representing the position of the point in milliseconds:
+You can create cue points using the **WaveFile.setCuePoint()** method. The method takes a object with the cue point data and creates a cue point in the corresponding position of the file. The only required attribute of the object is *position*, a number representing the position of the point in milliseconds:
 ```javascript
-// to create a cue point the position in milliseconds
-// is the only required attribute in the cue point data object
+// to create a cue point
 wav.setCuePoint({position: 1500});
 ```
 
-You can also create cue points with labels by defining a 'label' attribute:
+You can also create cue points with labels by defining a *label* attribute:
 ```javascript
 // to create a cue point with a label
 wav.setCuePoint({position: 1500, label: 'some label'});
 ```
 
-To delete a cue point use **WaveFile.deleteCuePoint()** informing the index of the point. Points are ordered according to their position. The first point is indexed as 1.
+To delete a cue point use **WaveFile.deleteCuePoint()** informing the index of the point. Points are ordered according to their position. **The first point is indexed as 1.**
 ```javascript
 wav.deleteCuePoint(1);
 ```
 
 Mind that creating or deleting cue points will change the index of other points if they exist.
 
+To list all the cue points in a file, in the order they appear:
+```javascript
+let cuePoints = wav.listCuePoints();
+```
+This method will return a list with cue points ordered as they appear in the file.
+```javascript
+[
+  {
+    position: 500, // the position in milliseconds
+    label: 'cue marker 1',
+    end: 1500, // the end position in milliseconds
+    dwName: 1,
+    dwPosition: 0,
+    fccChunk: 'data',
+    dwChunkStart: 0,
+    dwBlockStart: 0,
+    dwSampleOffset: 22050, // the position as a sample offset
+    dwSampleLength: 3646827, // the region length as a sample count
+    dwPurposeID: 544106354,
+    dwCountry: 0,
+    dwLanguage: 0,
+    dwDialect: 0,
+    dwCodePage: 0,
+  },
+  //...
+];
+```
+
 ### Create regions in files
 You can create regions using the **WaveFile.setCuePoint()** method. Regions are cue points with extra data.
 
-If you specify a 'end' attribute in the object describing the cue point, the point will be created as a region. The 'end' attribute is the end of the region, in milliseconds, counting from the start of the file:
+If you define a not null *end* attribute in the object describing the cue point, the point will be created as a region. The *end* attribute should be the end of the region, in milliseconds, counting from the start of the file, and always greater than the *position* of the point:
 ```javascript
 // to create a region with a label:
 wav.setCuePoint({position: 1500, end: 2500, label: 'some label'});
 ```
+You can also define the following optional properties when creating a region:
+- dwPurposeID
+- dwCountry
+- dwLanguage
+- dwDialect
+- dwCodePage
 
 ### RIFX
 **wavefile** can handle existing RIFX files and create RIFX files from scratch. Files created from scratch will default to RIFF; to create a file as RIFX you must define the container:
@@ -597,20 +631,9 @@ WaveFile.deleteCuePoint(index) {}
 /**
  * Return an array with all cue points in the file, in the order they appear
  * in the file.
- *  Objects representing standard cue points look like this:
- *   {
- *     milliseconds: 500 // the position in milliseconds
- *     label: 'cue marker 1',
- *     dwName: 1,
- *     dwPosition: 0,
- *     fccChunk: 'data',
- *     dwChunkStart: 0,
- *     dwBlockStart: 0,
- *     dwSampleOffset: 22050 // the position as a sample offset
- *   }
- * Objects representing regions look like this:
+ * Objects representing cue points/regions look like this:
  *   {
- *     milliseconds: 500 // the position in milliseconds
+ *     position: 500, // the position in milliseconds
  *     label: 'cue marker 1',
  *     end: 1500, // the end position in milliseconds
  *     dwName: 1,
@@ -628,7 +651,7 @@ WaveFile.deleteCuePoint(index) {}
  *   }
  * @return {!Array<Object>}
  */
-listCuePoints() {}
+WaveFile.listCuePoints() {}
 
 /**
  * Update the label of a cue point.
@@ -683,19 +706,25 @@ WaveFile.set_PMX(_PMXValue) {};
 ```
 
 #### WaveFile.listCuePoints()
-This method returns a list of objects, each object representing a cue point.
-The list looks like this:
+This method returns a list of objects, each object representing a cue point or region. The list looks like this:
 ```javascript
 [
   {
-    milliseconds: 500
+    position: 500, // the position in milliseconds
     label: 'cue marker 1',
+    end: 1500, // the end position in milliseconds
     dwName: 1,
     dwPosition: 0,
     fccChunk: 'data',
     dwChunkStart: 0,
     dwBlockStart: 0,
-    dwSampleOffset: 22050
+    dwSampleOffset: 22050, // the position as a sample offset
+    dwSampleLength: 3646827, // the region length as a sample count
+    dwPurposeID: 544106354,
+    dwCountry: 0,
+    dwLanguage: 0,
+    dwDialect: 0,
+    dwCodePage: 0
   },
   // ...
 ]

diff --git a/dist/wavefile.js b/dist/wavefile.js
diff --git a/docs/index.html b/docs/index.html
@@ -79,6 +79,7 @@ <h2>Notice</h2>
 <li>Change the bit depth of the audio</li>
 <li>Read and write RIFF tags</li>
 <li>Set and delete cue points and their labels</li>
+<li>Create regions in wav files</li>
 <li>Encode/decode files as ADPCM, A-Law and μ-Law</li>
 <li>Turn RIFF files to RIFX and RIFX to RIFF</li>
 <li>Create or edit BWF metadata (&quot;bext&quot; chunk)</li>
@@ -254,25 +255,57 @@ <h3>Add RIFF tags to files</h3>
 <pre class="prettyprint source lang-javascript"><code>wav.deleteTag(&quot;ICMT&quot;);
 </code></pre>
 <h3>Add cue points to files</h3>
-<p>You can create cue points using the <strong>WaveFile.setCuePoint()</strong> method. The method takes a object with the cue point data and creates a cue point in the corresponding position of the file. The only required attribute of the object is 'position', a number representing the position of the point in milliseconds:</p>
-<pre class="prettyprint source lang-javascript"><code>// to create a cue point the position in milliseconds
-// is the only required attribute in the cue point data object
+<p>You can create cue points using the <strong>WaveFile.setCuePoint()</strong> method. The method takes a object with the cue point data and creates a cue point in the corresponding position of the file. The only required attribute of the object is <em>position</em>, a number representing the position of the point in milliseconds:</p>
+<pre class="prettyprint source lang-javascript"><code>// to create a cue point
 wav.setCuePoint({position: 1500});
 </code></pre>
-<p>You can also create cue points with labels by defining a 'label' attribute:</p>
+<p>You can also create cue points with labels by defining a <em>label</em> attribute:</p>
 <pre class="prettyprint source lang-javascript"><code>// to create a cue point with a label
 wav.setCuePoint({position: 1500, label: 'some label'});
 </code></pre>
-<p>To delete a cue point use <strong>WaveFile.deleteCuePoint()</strong> informing the index of the point. Points are ordered according to their position. The first point is indexed as 1.</p>
+<p>To delete a cue point use <strong>WaveFile.deleteCuePoint()</strong> informing the index of the point. Points are ordered according to their position. <strong>The first point is indexed as 1.</strong></p>
 <pre class="prettyprint source lang-javascript"><code>wav.deleteCuePoint(1);
 </code></pre>
 <p>Mind that creating or deleting cue points will change the index of other points if they exist.</p>
+<p>To list all the cue points in a file, in the order they appear:</p>
+<pre class="prettyprint source lang-javascript"><code>let cuePoints = wav.listCuePoints();
+</code></pre>
+<p>This method will return a list with cue points ordered as they appear in the file.</p>
+<pre class="prettyprint source lang-javascript"><code>[
+  {
+    position: 500, // the position in milliseconds
+    label: 'cue marker 1',
+    end: 1500, // the end position in milliseconds
+    dwName: 1,
+    dwPosition: 0,
+    fccChunk: 'data',
+    dwChunkStart: 0,
+    dwBlockStart: 0,
+    dwSampleOffset: 22050, // the position as a sample offset
+    dwSampleLength: 3646827, // the region length as a sample count
+    dwPurposeID: 544106354,
+    dwCountry: 0,
+    dwLanguage: 0,
+    dwDialect: 0,
+    dwCodePage: 0,
+  },
+  //...
+];
+</code></pre>
 <h3>Create regions in files</h3>
 <p>You can create regions using the <strong>WaveFile.setCuePoint()</strong> method. Regions are cue points with extra data.</p>
-<p>If you specify a 'end' attribute in the object describing the cue point, the point will be created as a region. The 'end' attribute is the end of the region, in milliseconds, counting from the start of the file:</p>
+<p>If you define a not null <em>end</em> attribute in the object describing the cue point, the point will be created as a region. The <em>end</em> attribute should be the end of the region, in milliseconds, counting from the start of the file, and always greater than the <em>position</em> of the point:</p>
 <pre class="prettyprint source lang-javascript"><code>// to create a region with a label:
 wav.setCuePoint({position: 1500, end: 2500, label: 'some label'});
 </code></pre>
+<p>You can also define the following optional properties when creating a region:</p>
+<ul>
+<li>dwPurposeID</li>
+<li>dwCountry</li>
+<li>dwLanguage</li>
+<li>dwDialect</li>
+<li>dwCodePage</li>
+</ul>
 <h3>RIFX</h3>
 <p><strong>wavefile</strong> can handle existing RIFX files and create RIFX files from scratch. Files created from scratch will default to RIFF; to create a file as RIFX you must define the container:</p>
 <pre class="prettyprint source lang-javascript"><code>wav.fromScratch(1, 48000, '16', [0, 1, -3278, 327], {&quot;container&quot;: &quot;RIFX&quot;});
@@ -573,20 +606,9 @@ <h3>The WaveFile methods</h3>
 /**
  * Return an array with all cue points in the file, in the order they appear
  * in the file.
- *  Objects representing standard cue points look like this:
- *   {
- *     milliseconds: 500 // the position in milliseconds
- *     label: 'cue marker 1',
- *     dwName: 1,
- *     dwPosition: 0,
- *     fccChunk: 'data',
- *     dwChunkStart: 0,
- *     dwBlockStart: 0,
- *     dwSampleOffset: 22050 // the position as a sample offset
- *   }
- * Objects representing regions look like this:
+ * Objects representing cue points/regions look like this:
  *   {
- *     milliseconds: 500 // the position in milliseconds
+ *     position: 500, // the position in milliseconds
  *     label: 'cue marker 1',
  *     end: 1500, // the end position in milliseconds
  *     dwName: 1,
@@ -604,7 +626,7 @@ <h3>The WaveFile methods</h3>
  *   }
  * @return {!Array&lt;Object>}
  */
-listCuePoints() {}
+WaveFile.listCuePoints() {}
 
 /**
  * Update the label of a cue point.
@@ -658,18 +680,24 @@ <h3>The WaveFile methods</h3>
 
 </code></pre>
 <h4>WaveFile.listCuePoints()</h4>
-<p>This method returns a list of objects, each object representing a cue point.
-The list looks like this:</p>
+<p>This method returns a list of objects, each object representing a cue point or region. The list looks like this:</p>
 <pre class="prettyprint source lang-javascript"><code>[
   {
-    milliseconds: 500
+    position: 500, // the position in milliseconds
     label: 'cue marker 1',
+    end: 1500, // the end position in milliseconds
     dwName: 1,
     dwPosition: 0,
     fccChunk: 'data',
     dwChunkStart: 0,
     dwBlockStart: 0,
-    dwSampleOffset: 22050
+    dwSampleOffset: 22050, // the position as a sample offset
+    dwSampleLength: 3646827, // the region length as a sample count
+    dwPurposeID: 544106354,
+    dwCountry: 0,
+    dwLanguage: 0,
+    dwDialect: 0,
+    dwCodePage: 0
   },
   // ...
 ]