[[BackLinksMenu]]

[[TicketQuery(summary=AUDIO_RECORDING_R0, format=table, col=summary|owner|status|type|component|priority|effort|importance, rows=description|analysis_owners|analysis_reviewers|analysis_score|design_owners|design_reviewers|design_score|implementation_owners|implementation_reviewers|implementation_score|test_owners|test_reviewers|test_score|)]]

= Analysis =

== Overview ==

Audio recording allows the user to record audio, which is then stored as an audio resource in the book. This could be done with a dialogue that is invoked from the menu bars..

== Task requirements ==

 * User should select recording mode by selecting '''Insert > Insert Audio Recording''' from the menus.
 * User should be able to start recording (by pressing record button).
 * User should be able to stop recording (by pressing stop button).
 * When recording has been stopped, the recording should be added to the resources as a WAV with the date and time as its name.

== Task result ==
Source code.

== Implementation idea ==
 * Audio recording should be implementing using the Java Media Framework library.
 * The existing framework in org.sophie2.main.media.fobs should be used for registering audio records.
 * The existing framework in org.sophie2.base.media should be used for manipulating audio record objects.

== Related ==
[wiki:MEDIA_FRAME_CONTROLS_R0]

[wiki:AUDIO_CONTENT_R0]

== How to demo ==
Make a new Sophie book, start recording, record audio, stop recording. Put audio of the recording on the page and play it back.

= Design =
 * Implementation should follow the class diagram below:
[[Image(source:/trunk/sophie2-platform/modules/org.sophie2.main.media.fobs/doc/AUDIO_RECORDING_R0.jpg)]]
 * An example of audio capture with JMF can be seen at http://java.sun.com/javase/technologies/desktop/media/jmf/2.1.1/guide/JMFCapturing.html (Example 5-4)
 * To record data successfully on different platforms the capture device should be set to "javasound://" like this: ''Manager.createProcessor(new MediaLocator("javasound://"));''.
 * The dialog for recording will have two buttons - record and stop.
 * When the recording is stopped the audio resource is inserted into the page as an audio frame containing the new audio record.
 * The record has a time limit which is one hour by default, if this limit is exceeded then the recording stops and the media is inserted as if recording stopped.
 * To create a audio resource a temporary file will be created which is wrapped in a BinDataSource object.
 * Class CaptureParameters will be immutable.
 * A JUnit test case is created that will test registration/unregistration as well as capture for a short period. [3185],  [3186]
 * The following classes will be created:
  * StateHelperEntry (The state helper encapsulates the Processor which actually does the capture)
  * CaptureParameters
  * AudioCaptureDialog
  * AudioCaptureDialogInput
  * InsertAudioRecordItem
 * The following classes will be changed:
  * MediaEngine
  * JMFEngine
  * MediaLogic
  * MasterAudioEngine
  * MasterVideoEngine
  * MainFuncMediaModule
  * SkinDefIds

Design related code merged into the trunk in [3196].
= Implementation =
 * The implementation differs from design in some points:
  * In class StateHelperEntry two more properties where added - DataSink fileWriter (in order to close the DataSink once capture is done) and Processor (to close the StateHelper once capture is done).
  * MainAppModule was changed to register the AudioCaptureDialog.
[[BR]]
[3236][[BR]]
Merged to the trunk in [3346].

= Testing =
^(Place the testing results here.)^

= Comments =
 * In Sophie 1, the interface was a palette; a dialogue window might make more sense. 
 * If we don't actually have audio playback, maybe we can't demonstrate playback in this iteration.
 * Audio should be saved in a compressed form rather than as a raw WAV; this can be done in a later implementation. 
 * In Sophie 1, after recording audio had stopped, users saw a "play" and "save" button. "Play" played back the recording (so the user could tell if it were good or not); "Save" saved it to the resources.
 * Does this work differently on different OSes?