doc.scripts.AudacityToDTB.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of pipeline1-adapter Show documentation
The newest version!




	
	Audacity Save-as-DAISY
	


Pipeline Script: Audacity Save-as-DAISY [BETA]



Overview
Input Requirements
From Audacity project to DTB
Configuration
Known issues in this beta




Overview

This script creates a DAISY/NISO NCX (audio) only digital talking book from an Audacity project. 
By using markers in the Audacity project in a predefined way in the recorded audio, the resulting DTB can contain headings and pagenumbers

.

Note: when you save the Audacity project, you must choose the option to import the audio files into the project.

A special "set-the-duration" technique (described below) also allows the pagenumbers  to become skippable in the output DTB.

This script has been tested against Audacity version 1.3.7. Earlier versions are not supported.

Input Requirements
An Audacity project file (*.aup), following the DTB-enabling conventions as described in the section below.

Using Audacity to create an NCX-Only DTB

Cardinal Rule One For each wave track in Audacity, there must be a label track immediately below. 

You can record your project using one wavetrack only, or you can use several wavetracks, as long as all wavetracks have a label track immediately below. The image below shows an Audicity DTB project which uses two Wave tracks; each wave track has a label track immediately below.



Creating headings

For each heading you want create, drop a Marker at the appropriate time position in the Label track below the concerned Audio track. The markers value must begin with h1, h2, h3, h4, h5, or h6 for the marker to be detected as a heading.
The text following in the marker value will become the heading text. For example, a marker value of h2 Chapter 3 Galapagos will create a level 2 heading with the title "Chapter 3 Galapagos".

It is important to remember that heading must be in numbered order. That is an h2 must follow an h1, another h2 or an h3.

Creating pages
For each page you want create, drop a Marker at the appropriate time position in the Label track below the concerned Audio track. The markers value must begin with p for the marker to be detected as a pagenumber.
For example, the marker value "p56" will create a normal pagenumber with the value "56". 
You can also create special and front pages; the marker value pIV will create a front page with the roman numeral four. The marker value pA23 will create a page-special with the value A23.



You can also have pagenumbers be autonumbered during the Pipeline DTB generation phase. 
Simply create a marker with the value p and then activate the autonumbering feature of this script in the Pipeline user interface. Note - if you activate page renumbering while saving as DAISY, all normal pages will be renumbered, even those that were actually given a value in the Marker value field.

Creating general phrases
Any marker added (with or without duration) that does not use the heading or page tokens as described above will be regarded as general DAISY phrases.



Use markers with duration if you can!
By creating markers that have a duration (i.e. a start and an end point), you will provide for a maximum quality output DTB. Adopt this technique in the following way:

Create markers that spans each heading announcement (the heading will not become skippable, this just enables proper labels to be set in the NCX)
Create markers that spans each page number announcement (the page number will become skippable).


The picture below shows a page announcment whose start and end point has been marked using a Marker with duration.


Title and Author
The conversion process assumes that the reading of the documents title is the first marked phrase of the recording, and that the documents author is the second marked phrase.
You would typically mark the first phrase as also being a heading one, and the second as being a general phrase.



Metadata


The audacity metadata editor will capture the following fields and bring them into the DTB:

Artist Name
Will be captured as the publication author (dc:creator)
Album title
Will be captured as the publication title (dc:title)	
Year
Will be captured as the publication date (dc:date). You should use the the syntax YYYY-MM-DD in this field.
uid
Will be captured as the publication identifier (dc:identifier). This meta entry will have to be created (use the "add" button of the Audacity metadata editor)
lang
Will be captured as the publication language (dc:language). This meta entry will have to be created (use the "add" button of the Audacity metadata editor)

publisher
Will be captured as the book's publisher (dc:publisher). This meta entry will have to be created (use the "add" button of the Audacity metadata editor)




If you dont provide the metadata required for a valid DTB, dummy values will be inserted during the Save-as-DAISY process. Dont forget to fix these (in the .opf) before finalizing the project!

From Audacity project to DTB

Make sure the Audacity project is saved (*.aup). Note - at this time you must not use any of the "Export as..." features of Audaciy. Just save the project, and if you are prompted to "import external files", accept the import.
Open the Pipeline, select the "Audacity Save-as-DAISY script" (available in the creation/advanced directory)
For the input file, point to the Audacity *.aup file that you saved in the steps above
Add the additional required parameters, and launch the conversion process.
Note: the output is a validated z3986-2005 NCX-only DTB, using wav files. In later (post-beta) versions of this script, MP3 encoding and Daisy 2.02 downgrade features can be added.



Configuration
	
		Input file
		Required. The input Audacity project file (*.aup)
	
		Output directory
		Required. The directory to store the output in. This can be set as the same as the input directory, but it is recommended to use another directory than the input directory.

		Page auto numbering
		Optional. Select whether to renumber all normal page numbers in the book, and if so which page to start from.
		
	
	
Known issues in this beta	

  Sketchy support for "uncommon" sample rates
  Certain sample rates in the input audio files can cause the output audio to sound like "static". Until this issue is fixed, make sure to use "standard" sample rates (such as 44.1k) and bit depths (such as 16 bit) in the input audio files. You can use Audacity to easily do this conversion.
Also, to be on the safe side, it is recommended to make a test Save-as-DAISY run early on in the project (before doing any extensive editing) and assure that the output audio files sound ok.