media.eh

Basic media support. More...

use "media.eh"

Types

type Player < Any;

Functions

def get_supported_ctypes(): [String];
def play_tone(note: Int, duration: Int, volume: Int = 100);
def Player.close();
def Player.get_ctype(): String;
def Player.get_duration(): Long;
def Player.get_time(): Long;
def Player.new(in: IStream, ctype: String): Player;
def Player.set_loops(count: Int);
def Player.set_time(time: Long);
def Player.start();
def Player.stop();

Description

This header provides basic support for media playback. All functions in this header may raise ERR_MEDIA error if an error occurs during media playback (for instance, if sound is turned off on device or if device is busy).

Tone generation

Simple tones can be produced using function play_tone(note, duration, volume). Here This function returns immediately, note is played back in the background. 

/* Playing "Mary had a little lamb" */
use "media"
use "sys"

const C4 = 60  // middle C
const D4 = C4 + 2
const E4 = C4 + 4
const G4 = C4 + 7
const PAUSE = -1
const TEMP = 250

def main(args: [String]) {
  var melody = [
    E4, D4, C4, E4,
    E4, E4, E4, PAUSE,
    D4, D4, D4, PAUSE,
    E4, G4, G4, PAUSE,
    E4, D4, C4, E4,
    E4, E4, E4, PAUSE,
    D4, D4, E4, D4, C4
  ]
  for (var i=0, i<melody.len, i+=1) {
    if (melody[i] != PAUSE)
      play_tone(melody[i], TEMP)
    sleep(TEMP)
  }
}

Players and content types

Player controls rendering of a time based media data (audio or video). To create new player you need to specify input data (in form of IStream) and the content type in form of MIME type string. Here are few common MIME types
Content type Common extensions Description
audio/x-wav .wav .wave Wave audio files
audio/basic .au .snd AU audio files
audio/mpeg .mp3 MP3 audio files
audio/midi .mid .midi MIDI files
audio/x-tone-seq .jts Tone sequences
Note, that device may not support all of these formats. Standard requires only support of WAV and tone sequences. The list of content types supported by particular device can be obtained using get_supported_ctypes(). 
/* Simple playback with looping */

var input = readurl("http://mywebsite/sound.wav")
var player = new Player(input, "audio/x-wav")
player.loops = 5
player.start()

Type details

type Player < Any;
A player of media data.

Function details

def get_supported_ctypes(): [String];
Returns list of all supported content types.

def play_tone(note: Int, duration: Int, volume: Int = 100);
Plays a specified tone. A note is in the range 0..127. A volume is in the range 0..100. A duration is given in milliseconds and must be positive.

This function is non-blocking, it returns immediately and note is played back in the background.

def Player.new(in: IStream, ctype: String): Player;
Creates new player with given data source and content type.

def Player.get_ctype(): String;
Returns the content type of the media that is being played back by this player.

def Player.set_loops(count: Int);
Sets the number of times the player will loop and play the content. By default, the media is played once. If loop count is set to -1, content will be played indefinitely.

def Player.get_duration(): Long;
Returns the duration of the media in milliseconds.

def Player.get_time(): Long;
Returns current position of the media in milliseconds. If current position is unknown, the function returns -1.

def Player.set_time(time: Long);
Sets current position in the media to play from. For some content types may be not very accurate. There are media types that cannot support the setting of media time, for these types, ERR_MEDIA error is raised.

def Player.start();
Starts playback of this player. If player was stopped previously, playback is resumed from where it was previously stopped. If the player has reached the end of media, calling start() will automatically start the playback from the beginning of the media.

def Player.stop();
Pauses playback at the current media time.

def Player.close();
Closes this player and releases its resources. Calling this method will also close associated input stream.