User:Stevethefiddle/Sample Data Export

Peter 19Jun12: initial editorial review:

• checked links - a couple are broken (noted with ednotes)
• tweaked a little for readability
• Connie had a go at the lists - she says: you don't have full stops at the end of list items unless it's a full sentence.
• changed the formatting ff divs to Bill's modern stylew with the curly brackets

Sample Data Export reads the values of successive samples from the selected audio and prints to a file. Further information may be added as a 'header' at the top of the page.

Accessed by: Analyze > Sample Data Export...

Controls

Show Help File:

• No: Does not show the help screens. To run Sample Data Export this option must be selected.
• Overview: Displays a help screen including a brief overview and descriptions of the first 3 controls.
• File Format: Displays a help screen including a brief description of the file output options.
• Header Text: Displays a help screen including a brief description of the file header options.
• Output Files: Displays a help screen about setting the file output location.
• Save Help File: Saves all four help screens in a single text file.

Limit output to first: <n> samples

• The number of samples processed will be the number of samples in the selection, up to a maximum of the number entered here.
  • Sample Data Export is limited internally to an absolute maximum of 1 million samples.
  • Processing a large number of samples can create extremely large output files that may be difficult to open. For HTML output it is advisable to limit the number of samples to a maximum of a few hundred to avoid creating an excessively large html file.
  • The track sample rate indicates the number of samples per second and the number of samples in a selection may be viewed in the Selection Toolbar.

Measurement scale:

Sample values may be displayed on a linear scale +/- 1 (as in the Audacity audio track Waveform view) or on a dB scale relative to full scale (as in the Waveform (dB) view).

File data format:

Peter 19Jun12: broken link below - goes to an edit page

Following any header information:

• Sample List (txt): produces a plain text file with a list of sample values.
• Indexed List (txt): produces a plain text file with an indexed list of sample values: sample number followed by sample value.
• Time Indexed (txt): produces a plain text file with the time (relative to the start of the selection) followed by sample value
• Data (csv): produces a CSV file that contains the sample values separated by commas. This may be suitable for importing into spreadsheet applications for further analysis.
• Web Page (HTML): produces an HTML 5 document that contains all of the header information and a table of sample data with sample number, time, linear and dB values. Browsers that are not HTML 5 compliant may not display the page correctly.

Include header information:

• None: Prints only the optional header text (leave blank for none) followed by the sample data.
• Minimal: Prints a minimal header that contains:
  • The sample rate
  • Units (linear or dB)
  • Optional header text (leave blank for none)
• Standard: In addition to the minimal header information, the following is also included:
  • File name
  • Number of samples
  • Duration (seconds)
  • Mono/Stereo
• All: In addition to the standard header information, the following is also included:
  • peak amplitude linear and dB
  • Unweighted rms level (dB)
  • DC offset

For text and csv formatted files, file header data may be displayed in the debug window if the effect is run using the Debug button rather than the OK button.

Optional header text:

This is provided for adding notes to the output file. In text files, use ~~% to start a new line, in HTML files use <br>.

Channel layout for stereo:

The plain text and csv formatted files may be set to print stereo tracks as either alternate left channel sample / right channel sample:

 1	0.59528
 1	0.59528
 2	0.56063
 2	0.56063
 3	0.52377
 3	0.52377
 ...

or all of the left channel followed by all of the right channel:

 Left Channel.

 1	0.59528
 2	0.56063
 3	0.52377
 ...


 Right Channel.

 1	0.59528
 2	0.56063
 3	0.52377
 ...

Show messages:

• Yes: (default) Error, warning and confirmation messages will be shown after processing.
• Errors Only: Only error messages will be shown on completion.
• None: No messages will be shown on completion.

Normally the default setting should be used.

It may be useful to disable confirmation messages if Sample Data Export is to be used in a Chain for batch processing (see below).

Peter 19Jun12: the link to "below" above is broken

File name:

The desired name of the output file. A file extension is not required as it will be added automatically.

Output folder:

The default output folder is the Home directory.

This is normally:

• Microsoft Windows Vista and 7: <root>\Users\<username>
• Microsoft Windows 2000, XP and 2003 : <root>\Documents and Settings\<username>
• Mac OS X: /Users/<username>
• Linux: /home/<username>

To select a different output folder, enter the full path name. The output folder must exist.

The abbreviation ~/ may be used for the home directory.

A notification message is displayed on completion indicating the name and location of the file.

Allow files to be overwritten:

(Default = No) When set to No files will not be overwritten. If the selected file already exists the chose filename will be appended with a number. For example, if output.txt is the chosen file name and that file already exists, the chosen name will be changed to output1.txt. If that file also exists the name will be changed to output2.txt, and so on until a unique name is found.

When set to Yes if the file already exists it will be overwritten.

If you select multiple tracks and Allow files to be overwritten is set to No, they will be saved to separate files with a number appended to the name. If you set Allow files to be overwritten to Yes, only the last file for multiple tracks will be retained.

Batch processing with Sample Data Export

Peter 19Jun12: you don't want or need the "As of Audacity version 2.0.1" - as this is the alpha maual for 2.0.1 not the 2.0.0 manual.

Nyquist effect plug-ins are supported in Chains, but Analyze plug-ins are not supported. To use Sample Data Export in a Chain it is necessary to convert it into an Effect plug-in. To do this, the file sample-data-export.ny must be edited in a plain text editor (such as Notepad on Windows).

The file sample-data-export.ny can be found in the plug-Ins folder inside the Audacity installation folder. On Windows computers, this is usually under "Program Files". On Mac OS X, it is usually under "Applications". On Linux, you can use various plug-in locations. To convert Sample Data Export into an Effect type plug-in, open the file in a plain text editor and change the third line:

 ;type analyze

to:

 ;type process

Save the file in the same location and restart Audacity. Sample Data Export... will now appear underneath the divider in the "Effect" menu rather than the "Analyze" menu, and will be available for use in a Chain.