Contentschema

# Overview

## Purpose

This is the low level schema for describing content and interactivity of the talking book device.

This schema is intended to be:

• A complete set of commands to meet the needs of the functional specification,
• Implementable in the Soft Player,
• Possible to flatten and compile to a format usable to the physical player,
• Compatible with similarly scoped specifications, such as DAISY, so TalkingBook can use their content,
• Flexible enough to accommodate unforeseen, creative uses for the player.

## Content Structure

The main structural elements are Device , Package, Folder, File, and Block.

All of these elements are very similar in that they each are a container for:

• Segment of audio content: a group of files, a file, or a segment within a file
• Actions that occur at the beginning and end of the segment of audio content
• Actions that occur when buttons are pressed
• Child container elements.

Additionally each of these container elements can serve as a:

• An arbitrary content class, such as “Chapter”, “Page”, etc…
Container Element Description Additional Attributes Child Containers
Device Contains the default button event handlers. Only applies to the soft player. Package
Package The root element for deployed sets of audio content. Also used to scope container ids and flags Folder, File
Folder A grouping of files or child folders - Folder, File
File A single audio file Reference to file Block
Block A segment within an audio file. Start offset and duration Block

At its simplest, containers just identify the files in a distribution package:

(1)
\begin{align} Package \left\{ \begin{array}{ c c } File \\ File \\ File \end{array} \end{align}

More complex container structures support features like special break points, navigation targets, or context-specific button actions:

(2)
\begin{align} Package \left\{ \begin{array}{ c c } Folder \left\{ \begin{array}{ c c } File \left\{ \begin{array}{ c c } Block \left\{ \begin{array}{ c c } Block \\ Block \end{array} \\ Block \end{array} \\ File \left\{ \begin{array}{ c c } Block \end{array} \end{array} \\ Folder \left\{ \begin{array}{ c c } File \left\{ \begin{array}{ c c } Block \left\{ \begin{array}{ c c } Block \end{array} \end{array} \end{array} \end{array} \end{align}

## Event Handlers

Each container may have event handlers to support interactivity and special features.

Event Handler Description Occurance
OnStart Actions to perform prior to playing the audio in a container. 0..1
OnFinish Actions to perform after playing the audio in a container. 0..1
OnButton Actions to perform when a button is pressed. 0..n

Each event handler will contain one or more ActionSet elements, which list the sequence of actions to peform. An event handler may contain multiple ActionSet elements with conditional tests to provide alternate responses to events using FlagTest elements.

## Schema

The structure of the talking book content schema is summarized in the following diagram and an XML Schema

# Element Reference

## Container Elements

### Device

The Device element defines the default button event handlers for the entire device. This element is only used in the Soft Player, and is not used in content authoring.

When used with the Soft Player, this element may contain multiple Package elements.

### Package

The Package element is the root element for a distributed set of audio content. A package is also used to scope container IDs and flags.

A Package element may contain multiple Folder and File child containers.

A Package element may also contain one OnStart, one OnFinish, and many OnButton event handlers.

Attribute Description
ID The ID of the container. Must be unique across all containers within the package.
Class The type or resolution of content within this container. Possible values are "Chapter", "Page", "Sentence", etc..

### Folder

The Folder is used to group a set of child File or Folder containers. This is used to share common event handlers or class definitions across multiple files. It may be contained within a Package or a Folder container.

A Folder element can contain multiple Folder and File child containers.

A Folder element may also contain one OnStart, one OnFinish, and many OnButton event handlers.

Attribute Description
ID The ID of the container. Must be unique across all containers within the package.
Class The type or resolution of content within this container. Possible values are "Chapter", "Page", "Sentence", etc..

### File

The File element is a container that represents a single audio file. It may be contained within a Package or Folder container.

The File element may contain many Block child containers.

A File element may also contain one OnStart, one OnFinish, and many OnButton event handlers.

Attribute Description
ID The ID of the container. Must be unique across all containers within the package.
Class The type or resolution of content within this container. Possible values are "Chapter", "Page", "Sentence", etc..
Href The path or url to the file containing the audio content

### Block

The Block element is a container that represents a segment of audio within a file. It must be contained within a File or a Block element.

The Block element may contain many Block child containers.

A Block element may also contain one OnStart, one OnFinish, and many OnButton event handlers.

Attribute Description
ID The ID of the container. Must be unique across all containers within the package.
Class The type or resolution of content within this container. Possible values are "Chapter", "Page", "Sentence", etc..
Offset The beginning of the segment of audio, defined as the number of milliseconds from the end of the previous sibling block. If this is the first block within the parent container, the offset is from the beginning of the parent container. The default value is zero.
Length The duration of the segment of audio. This may be omitted for the last block within a container, where it is assumed the block will extend to the end of the parent container.

#### Examples

The following file is 60 seconds long. It contains three blocks, one extending from 0 to 20 seconds, one from 20 to 40 seconds, and one 40 to 60 seconds.

<File Href="Lesson12.mp3">
<Block Length="20000">
</Block >
<Block Length="20000">
</Block >
<Block>
</Block>
</File>


The following file is 60 seconds long. It contains two blocks, one extending from 0-40 seconds, and the other from 55-60 seconds.

<File Href="Lesson12.mp3">
<Block Length="40000">
</Block>
<Block Offset="15000">
</Block>
</File>


The following file is 60 seconds long. It contains one block extending from 20 to 40 seconds.

<File Href="Lesson12.mp3">
<Block Offset="20000" Length="20000">
</Block>
</File>


## Event Handler Elements

The following elements support event handling.

### OnButton

Defines the actions that occur when a button is pressed. The actions defined within this event handler override the default actions of the button when one of the child ActionSets are executed.

The OnButton element may contain one or more ActionSet elements.

Attribute Description
Button The name of the button. These may change based on the final design of the device. The current values are: PlayPause, Next, Previous, VolumeUp, VolumeDown, Forward, Back, Option1, and Help
Action The button action to which this event handler applies. Possible values are Press, Release, and Hold. The Hold event is fired once a second when the button is held down.

### OnStart and OnFinish

The OnStart element contains actions to be beformed at the beginning of a segment of audio content.

The OnFinish elements contains actions to be beformed at the end of a segment of audio content. Also when a Goto element jumps to an end of a container, the actions within the OnFinish element are executed before moving to the next container.

Both elements may contain one or more ActionSet elements.

#### Example

The following example is from a shared block of audio content that tells a user that he has selected the wrong answer. After playing, the audio returns to the location that was previously pushed onto the stack.

<File ID="WrongAnswer" Href="wronganswer.mp3">
<OnFinish>
<Goto>
<PopStack/>
</Goto>
</OnFinish>
</File>


### ActionSet

The ActionSet is used within a OnButton, OnStart or OnFinish element.

ActionSet defines the set of action elements to be executed when an event occurs. Optionally the ActionSet element can also contain FlagTest which must all evaluate to *true* for the ActionSet to be executed.

If the parent OnButton, OnStart or OnFinish element contains more than one ActionSet element, the first actionset element whose FlagTest elements evaluate to *true* is executed.

#### Example

The following example handles the Option1 button, when it is pressed during a wrong answer. Each time the user presses the button during the wrong answer he is told that he has selected the wrong answer and is returned to the beginning of the list of answers. However, the first time the user selects the wrong answer, he receives a hint.

In this case, the first ActionSet contains a FlagTest, while the second does not. This functions similarly to an if-else, switch-case-default, or xsl:choose-xsl:when-xsl:otherwise construct.

<OnButton Button="Option1" Action="Release">
<ActionSet>
<PushStack>
<Location Ref="Hint"/>
</PushStack>
<Goto>
</Goto>
</ActionSet>
<ActionSet>
<PushStack>
</PushStack>
<Goto>
</Goto>
</ActionSet>
</OnButton>


### FlagTest

FlagTest is used within an ActionSet element to conditionally control execution of that actionset.

Flags are set within other event handlers using the SetFlag action. Flags are scoped within the parent Package container.

Attribute Description
Flag The unique identifier of the flag. These IDs are scoped within the Package container.
Test The test to apply to the flag value. Valid values are "IsTrue", and "IsFalse". If a flag has not been assigned a value, it is assumed to be false.

The example is a Block that contains a multiple choice question. If the user clicks the Option button during the playback of correct choice (between 45 and 53 seconds in the audio track), the "CorrectChoice" flag will record that they answered correctly. The OnFinish event handler will tell them whether they answered correctly.

<File Href="question23.mp3" Class="Question">
<OnStart>
<ActionSet>
<SetFlag Flag="CorrectChoice" Value="false"/>
</ActionSet>
</OnStart>
<OnFinish>
<ActionSet>
<FlagTest Flag="CorrectChoice" Test="IsTrue"/>
<PushStack>
<Location Class="Question" Target="Next"/>
</PushStack>
<Goto>
<Location Ref="YouAreCorrect"/>
</Goto>
</ActionSet>
<ActionSet>
<PushStack>
<Location Class="Question" Target="Next"/>
</PushStack>
<Goto>
<Location Ref="ImSorryThatIsNotCorrect"/>
</Goto>
</ActionSet>
</OnFinish>
<Block Offset="45000" Length="8000">
<OnButton Button="Option1" Action="Release">
<ActionSet>
<SetFlag Flag="CorrectChoice" Value="true"/>
</ActionSet>
<OnButton>
</Block>
</File>


## Action Elements

The following elements are action elements.

### Play

Starts playing content at the current position

Attribute Description
Speed The playback speed, where 100 is normal speed

### Pause

Stops all playing, buttons still respond for 60 seconds, if no duration value is set. If a duration value is set, play will resume after that many milliseconds.

Attribute Description
Duration The duration after which playing should resume

### Stop

Starts playing content at the current position

### Goto

Moves to the specified location. It does not affect whether content is playing or not playing.

This element must have either a Location or PopStack child element.

Actions following a Goto element are not executed, unless PopStack is used when no locations are on the stack.

#### Examples

<Goto>
<Location Offset=”10000”/>
</Goto>


Jump to the beginning of the next container whose Class attribute equals ”Chapter”

<Goto>
<Location Target=”Next” Class=”Chapter”/>
</Goto>


Jump to the beginning of the container whose ID attribute equals ”Introduction”

<Goto>
<Location Ref=”Introduction”/>
</Goto>


<Goto>
<PopStack/>
</Goto>


### Location

Identifies a position within the audio content. It is used within the Goto or PushStack elements.

Attribute Description
Ref The ID value of another container. By default, this will go to the beginning of the container, unless another value for target is specified
Class If a target of "Next", "Previous", "Beginning", or "End" is chosen the target will be relative to the parent container with the same Class value.
Target One of the following values
* Beginning : The beginning of a container
* End : The end of a container
* Previous : The beginning of the previous container
* Next : The end of the next container
Offset The offset in milliseconds from the location specified by the combination of the Target, Class, and Ref attributes

Resolving the location attributes to an audio position begins with using the current audio position as the context. The attributes are then evaluated in the following order:

• Ref, if present, moves the context to the beginning of the container with a matching ID
• Class, if present, moves the context to the beginning of the parent container with a matching Class attribute
• Target, if present, moves the context to a relative position based on the boundaries of the current container
• Offset, if present, moves the context to a relative position based on the specified number of milliseconds

Examples are shown with the Goto element.

### PopStack

Used within the Goto element to Pop and goes to the most recent loction on the stack.

Examples are shown with the Goto element.

### PushStack

Pushes the specified location onto the stack. This is used to return to a location in the audio cotent after listening to a hyperlink.

Location is a required child element.

#### Example

The example shows two files. The first file is the main content. If the user presses the Option1 button while listening to IHaveADream.mp3, the bio.mp3 file will play, and then return to the previous position in IHaveADream.mp3.

<File Href="IHaveADream.mp3">
<OnButton Button="Option1" Action="Release">
<ActionSet>
<PushStack>
<Location>  <!-- With no attributes specified, defaults to current location -->
</PushStack>
<Goto>
<Location Ref="BiographicalNote"/>
</Goto>
</ActionSet>
</OnButton>
</File>

...

<File Href="bio.mp3" ID="BiographicalNote">
<OnFinish>
<ActionSet>
<Goto>
<PopStack/>
</Goto>
</ActionSet>
<OnFinish>
</File>


### ClearStack

Clears the location stack of all entries. The location stack is used by the PushStack and PopStack elements.

### SetFlag

Sets a flag to be true or false. If the flag does not exist, it is created. Flags can be used to support multi-button actions and record user responses.

Attribute Description
Flag The unique identifier of the flag. These IDs are scoped within the Package container.
Value A true or false value

#### Example

The following example is a Block that contains the correct answer to a multiple choice question. If the user clicks the Option button during the playback of this choice, the "CorrectChoice" flag will record that they answered correctly.

<Block Offset="45000" Length="8000">
<OnButton Button="Option1" Action="Release">
<ActionSet>
<SetFlag Flag="CorrectChoice" Value="true"/>
</ActionSet>
<OnButton>
</Block>


### SetLight

Sets the display of lights on the player.

Attribute Description
Light Indicates which lights are to be affected. Possible values are "Red" and "Green"
Mode Indicates the light setting. Possible values are "Off", "On", "SlowBlink", and "FastBlink"

#### Example

The following example sets the light to alternate slowly between Green and Yellow.

    <SetLight Light="Red" Mode="SlowBlink"/>
<SetLight Light="Green" Mode="On"/>


### SetVolume

Sets the player volume.

Attribute Description
Level The new volume level. Volume ranges from 0 to 100.
Relative If true, the value of the Level attribute is added to the current volume level.

### Show

Sends XHTML to the viewer if available.

Attribute Description
Append If “true”, the XHTML is appended to the XHTML in the viewer. Otherwise, the content in the viewer is replaced.
(inner xml) XHTML to be sent to the viewer

#### Example

<Show>
<p>We must forever conduct our struggle on the high plane of <u>dignity and discipline</u>.</p>
<p>We must not allow our creative protest to degenerate into physical violence.</p>
<p>Again and again, we must rise to the majestic heights of meeting physical force with <u>soul force</u>.</p>
</Show>


# Related Specifications

Specification Description
Daisy Digital Accessible Information System (ANSI/NISO Z39.86-2005) http://www.niso.org/standards/resources/Z39-86-2005.html Provides an accessible representation of a book. Subsets include the department of education recognized NIMAS (National Instructional Materials Accessibility Standard).
SMIL Synchronized Multimedia Integration Language http://www.w3.org/TR/REC-smil/
XSL-FO, XHTML W3C standards for printed page layout and web pages.