MediaClip (TotalCrossSDK 6.1.0 API)

java.lang.Object
- totalcross.ui.media.MediaClip

```
public class MediaClip
extends java.lang.Object
```
MediaClip is a sound clip. It will be updated in the future to support movie clips.
Support for sound clips varies between platforms. Some Java virtual machines support .wav and .au sound files and some versions don't seem to support either format.
Using a TotalCross Virtual Machine, .wav format sound clips are supported under Win32, WinCE and Palm OS. Under Win32 and WinCE, the .wav files for sound clips may exist in a file outside of the program's tcz file; the wav file can be stored inside a pdb/tcz file (and it has precedence over the one located in the file system).
In Palm OS, the wav must be added to the pdb (The Deployer does this automagically. Just reference a .wav and it will be added).
If you're playing a sound clip under a Windows CE device and you don't hear anything, make sure that the device is set to allow programs to play sounds. To check the setting, look at:
Start->Settings->Volume & Sounds
for the check box:
Enable sounds for: Programs
If it is not checked on, sound clips won't play.
Here is an example that plays a sound:
```
 File soundFile = new File("sound.wav", File.READ_WRITE);
 MediaClip s = new MediaClip(soundFile);
 s.start();
 
```
Under Palm OS, the currently supported formats are: uncompressed (PCM) or IMA 4-bit adaptive differential (IMA ADPCM). The ADPCM type is also known as DVI ADPCM; in a WAVE file, it's known as format 0x11. One or two-channels; All normal sampling rates (8k, 11k, 22.05k, 44.1k, 48, 96k).
Note that some Palm OS devices does not support 16bit waves, so better store them in 8bits.
MediaClip also support sound recording. When recording sound, you can only call the record and stop methods. Sound recording does not work under JavaSE.
The MediaClip events are broadcasted to the MainWindow controls.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CLOSED` The state of the MediaClip indicating that the MediaClip is closed.
`static int`	`HIGH` Used as a samplesPerSecond parameter in record method.
`static int`	`LOW` Used as a samplesPerSecond parameter in record method.
`static int`	`MEDIUM` Used as a samplesPerSecond parameter in record method.
`static int`	`PREFETCHED` The state of the MediaClip indicating that it has acquired all the resources to begin playing.
`static int`	`REALIZED` The state of the MediaClip indicating that it has acquired the required information but not the resources to function.
`static int`	`STARTED` The state of the MediaClip indicating that the MediaClip has already started.
`static int`	`UNREALIZED` The state of the MediaClip indicating that it has not acquired the required information and resources to function.
`static int`	`VOICE` Used as a samplesPerSecond parameter in record method.

Constructor Summary

Constructors
Constructor and Description

MediaClip(RandomAccessStream stream)
Create a MediaClip to play back or record a media from/to a RandomAccessStream.

Constructors
Constructor and Description
`MediaClip(RandomAccessStream stream)` Create a MediaClip to play back or record a media from/to a RandomAccessStream.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` Close the MediaClip and release its resources, WITHOUT closing the underlying stream. When the method returns, the MediaClip is in the CLOSED state and can no longer be used.
`int`	`getCurrentState()` Gets the current state of this MediaClip.
`void`	`record(int samplesPerSecond, int bitsPerSample, boolean stereo)` Starts recording the media until the `stop` method is called. Please notice you must explicitly close the MediaClip and close the underlying stream to make sure the data was fully written to the underlying stream.
`void`	`reset()` Stops the playback and reset the media time to 0.
`void`	`start()` Starts the MediaClip as soon as possible.
`void`	`stop()` Stops the MediaClip.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - UNREALIZED
```
public static final int UNREALIZED
```
    The state of the MediaClip indicating that it has not acquired the required information and resources to function.
    
    See Also:
    
    Constant Field Values
  - REALIZED
```
public static final int REALIZED
```
    The state of the MediaClip indicating that it has acquired the required information but not the resources to function.
    
    See Also:
    
    Constant Field Values
  - PREFETCHED
```
public static final int PREFETCHED
```
    The state of the MediaClip indicating that it has acquired all the resources to begin playing.
    
    See Also:
    
    Constant Field Values
  - STARTED
```
public static final int STARTED
```
    The state of the MediaClip indicating that the MediaClip has already started.
    
    See Also:
    
    Constant Field Values
  - CLOSED
```
public static final int CLOSED
```
    The state of the MediaClip indicating that the MediaClip is closed.
    
    See Also:
    
    Constant Field Values
  - VOICE
```
public static final int VOICE
```
    Used as a samplesPerSecond parameter in record method.
    
    See Also:
    
    Constant Field Values
  - LOW
```
public static final int LOW
```
    Used as a samplesPerSecond parameter in record method.
    
    See Also:
    
    Constant Field Values
  - MEDIUM
```
public static final int MEDIUM
```
    Used as a samplesPerSecond parameter in record method.
    
    See Also:
    
    Constant Field Values
  - HIGH
```
public static final int HIGH
```
    Used as a samplesPerSecond parameter in record method.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - MediaClip
```
public MediaClip(RandomAccessStream stream)
          throws IOException
```
    Create a MediaClip to play back or record a media from/to a RandomAccessStream. Currently the only media type supported is audio wave.
    It's important to notice that you may not use the same object for play back and record.
    
    Parameters:
    
    stream - The random access stream used to read (when playing) or writting (when recording) the data.
    
    Throws:
    
    IOException
    
    See Also:
    
    RandomAccessStream
- Method Detail
  - start
```
public final void start()
                 throws IOException
```
    Starts the MediaClip as soon as possible. If the MediaClip was previously stopped by calling stop, it will resume playback from where it was previously stopped. If the MediaClip has reached the end of media, calling start will automatically start the playback from the start of the media.
    
    When start returns successfully, the MediaClip must have been started and a STARTED event will be delivered. However, the MediaClip is not guaranteed to be in the STARTED state. The MediaClip may have already stopped (in the PREFETCHED state) because the media has 0 or a very short duration.
    
    If start is called when the MediaClip is in the STARTED state, the request will be ignored.
    
    Throws:
    
    IOException
  - stop
```
public final void stop()
                throws IOException
```
    Stops the MediaClip. It will pause the playback/record at the current media time.
    
    When stop returns, the MediaClip is in the PREFETCHED state. A STOPPED event will be delivered.
    
    If stop is called on a stopped MediaClip, the request is ignored.
    
    Throws:
    
    IOException
  - reset
```
public final void reset()
                 throws IOException
```
    Stops the playback and reset the media time to 0.
    
    Throws:
    
    IOException
  - getCurrentState
```
public int getCurrentState()
```
    Gets the current state of this MediaClip. The possible states are: UNREALIZED, REALIZED, PREFETCHED, STARTED, CLOSED.
    
    See Also:
    
    UNREALIZED, REALIZED, PREFETCHED, STARTED, CLOSED
  - close
```
public final void close()
                 throws IOException
```
    Close the MediaClip and release its resources, WITHOUT closing the underlying stream.
    
    When the method returns, the MediaClip is in the CLOSED state and can no longer be used. A CLOSED event will be delivered.
    
    If close is called on a closed MediaClip the request is ignored.
    
    Throws:
    
    IOException
  - record
```
public final void record(int samplesPerSecond,
                         int bitsPerSample,
                         boolean stereo)
                  throws IOException
```
    Starts recording the media until the stop method is called.
    Please notice you must explicitly close the MediaClip and close the underlying stream to make sure the data was fully written to the underlying stream.
```
 Platform specific limitations:
   Palm OS
       you may only record if the given stream is an instance of totalcross.io.File.
       the byte rate of the audio recorded must be under 60kbps. The byte rate is calculated as following:
           byte rate = samples per second * bits per sample * (stereo ? 2 : 1) / 8<br>
           If the byte rate exceeds this value, the record method will record in mono instead of stereo, and also 
           reduce also bits per sample to 8 if necessary.<br>
   BlackBerry
       the parameters received by record are not supported by BlackBerry, and therefore ignored.
       "The BlackBerry smartphone supports audio recording using two different formats, Adaptive Multi-Rate (AMR) 
       and 8kHz mono-16-bit Pulse Code Modulation (PCM). The default encoding used by the BlackBerry smartphone is AMR."
 
```
    Parameters:
    
    samplesPerSecond - may be VOICE (8000), LOW (11025), MEDIUM (22050) or HIGH (44100), otherwise an IllegalArgumentException is thrown.
    
    bitsPerSample - must be 8 or 16, otherwise an IllegalArgumentException is thrown.
    
    stereo - true for stereo recording or false for mono recording.
    
    Throws:
    
    IOException
    
    See Also:
    
    VOICE, LOW, MEDIUM, HIGH

Class MediaClip

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNREALIZED

REALIZED

PREFETCHED

STARTED

CLOSED

VOICE

LOW

MEDIUM

HIGH

Constructor Detail

MediaClip

Method Detail

start

stop

reset

getCurrentState

close

record