Prev: Module cam2: Extended Camera Functions
Module video: Playing and Recording Videos
| | |
| Compatibility of module video |
| Sony Ericsson UIQ2 phones do not offer a public video API. | Source file for module not found |
| Sony Ericsson UIQ3 phones offer only a poor public video API implementation. Some functions may throw ErrNotSupported. Recording audio data does not seem to be possible. Furthermore, trying to set unsupported recording configurations may crash the multimedia server and m. |
|
This module provides functions to play recorded videos on the device screen and audio, and to record videos with the device camera. Supported video file formats depend on the device, but generally include standard MP4 formats.
Each file has a recorded length (its "duration"). When playing files, there is also a "head position" the player is at or will start at. Both are measured in milliseconds.
Playing Videos
The video is shown on top of any other screen contents. Both the source region of the video frames and the destination region on the screen can be defined. Within certain limits, the video will then be scaled to match the requested regions.
A simple sequence to a play a video file is:
// open the video file
video.open('FasterThanMyShadow.mp4');
// start playing it
video.play();
// wait until playing has finished
video.wait()
|
Recording Videos
Recording videos is somewhat more complicated than playing videos, and may require subtle configuration, depending on the video formats and codecs supported by the device.
Recording a video also requires module module cam. The camera must be turned on via cam.on for video before any videos can be recorded.
Video recording also includes recording audio.
A simple sequence to record a video file is:
// turn camera on for video
cam.on(-1, true);
// create a new video file
video.create("MyVideo.mp4");
// setup for recording
video.setup();
// start recording
video.record();
// end recording after 10 seconds
sleep(10000);
video.stop();
video.close();
// turn the camera off
cam.off()
|
A complete video recording configuration supported by this module comprises:
- Recorder: the recorder plugin being used. Most devices normally offer just one recorder.
- Format: a recorder implements one or more video file formats (e.g. 3GP or MP4).
- Video Type: a format supports one or more video types (MIME types), e.g. video/mp4v-es.
- Audio Type: a recorder supports different audio types, e.g. AMR AAC.
- Frame Size: the video frame size (width and height in pixels), e.g. 176 x 144.
- Frame Rate: the video frame rate (frames per second), e.g. 15.
The configuration options have interdependencies. In particular, a specific recorder, format and video type only supports specific pairs of frame sizes and frame rates. The functions of this module generally throw
ErrNotSupported when attempting to configure invalid values.
To make producing a simple video a simple task, there are default values for all these options. The above code should thus work on all devices offering module video.
For those eager to dig into video configuration details, here is a complete configuration and recording sequence:
// pick a camera
cam.index(camIndex)
// check the available frame sizes for video
for s in cam.sizes(true) do ... end
// turn the camera on for video and select a frame size
cam.on(sizeIndex, true)
// check the available recorders and formats
for r in video.recorders do ... end
// create the video file and select recorder and format
available=video.create(file, recorderIndex, formatIndex)
// check the available audio and video types
for t in available['video'] do ... end
for t in available['audio'] do ... end
// setup the video, selecting frame rate and types
video.setup(true, frameRate, videoType, audioType)
// start recording, pause, continue...
video.record() ... video.stop() ... video.record() ...
// end recording
video.close()
// turn the camera off
cam.off()
|
video.busy
• function busy() → Boolean
Returns true if the video is still playing or being recorded. Returns false otherwise.
This function checks only the current m process: it will return false if another process is playing or recording a video.
video.play();
while video.busy() do
print "at",video.pos(),"ms";
sleep(1000)
end;
print "video replay ended"
→ at 600 ms
at 1600 ms
at 2700 ms
at 3800 ms
video replay ended
|
video.close
• function close() → null
Closes the currently accessed video file and frees all resources.
Throws ErrInUse if the file is being played or recorded. Thus, to forcibly close a file, use:
video.stop();
video.close()
|
video.create
• function create(file, rIndex=0, fIndex=0, maxSize=null) → Array
Permissions: Write(file)
| | |
| Compatibility of function video.create |
| Sony Ericsson UIQ3 phones do not support limiting the video size. | ErrNotSupported |
| Sony Ericsson UIQ3 phones: video and audio types supported by the format cannot be obtained. video and audio fields will be missing from the returned array. |
|
Creates a new video file for video recording, and returns the available video and audio types supported. Recording will use the recorder indicated by rIndex and its format indicated by fIndex, as defined by video.recorders:
- The recorder video.recorders[rIndex].
- The format video.recorders[rIndex]["formats"][fIndex].
If
maxSize is not null, recording will not write a video file larger than
maxSize bytes.
The supported types are returned as an array with two members:
| Key | Meaning | Type |
| video | Video types (MIME types) supported by the chosen recorder and format. | Array |
| audio | Audio types (four character codes) supported by the chosen recorder and format. | Array |
| |
cam.on must be called before calling this function. video.setup must be called afterwards, before recording can start.
Throws ErrInUse if a file is already being played or recorded. Throws ErrNotReady if cam.on has not been called. Throws ExcIndexOutOfRange if rIndex or fIndex do not indicate a valid recorder or format.
// turn the camera on for video recording
cam.on(-1, true);
// search for an MPEG-4 format
rIndex=0; fIndex=0;
for r=0 to len(video.recorders)-1 do
formats=video.recorders[r]["formats"];
for f=0 to len(formats)-1 do
if index(formats[f]["name"], "MPEG-4")>=0 then
rIndex=r; fIndex=f
end
end
end;
// create the new file
t=video.create("MyVideo.mp4", rIndex, fIndex);
// show the available types
for k in keys(t) do
print k,t[k]
end
→ video [video/H263-2000,video/H263-2000; profile=0,
video/H263-2000; profile=0; level=50,video/H263-2000;
profile=0; level=40,...<14>]
audio [ AMR, AAC]
|
video.hide
• function hide() → null
Hides the video display when playing videos. This can be called after video.stop to hide the last frame shown.
Throws ErrInUse if a video is playing (or recording).
See also video.show.
video.open
• function open(file) → Array
Permissions: Read(file)
| | |
| Compatibility of function video.open |
| Sony Ericsson UIQ3 phones: frame rate and audio presence flag cannot be obtained. fps and audio fields will be missing from the returned array. |
|
Opens a file for playing, and returns an array describing the video:
| Key | Meaning | Type |
| len | Duration of the video in milliseconds | Number |
| size | Width an height of the video frames (pixels) | Array |
| type | MIME file type of the video | String |
| fps | Frame rate (frames per second) | Number |
| audio | Does the video have audio data | Boolean |
| |
The source region is set to the whole frame, and the destination region to the entire screen. See video.view for more information about source and destination regions.
Throws ErrInUse if a file is already being played or recorded.
v=video.open('FasterThanMyShadow.mp4');
for k in keys(v) do
print k,v[k]
end
→ len 6919
size [320,240]
type video/MP4V-ES
fps 24
audio true
|
video.play
• function play() → null
Starts or continues playing the currently open video file in the current view setting.
This function immediately returns, before playing completes. Exceptions can therefore be thrown anywhere in the following code. Use video.wait to wait for completion.
Throws ErrInUse if the video unit is busy playing or recording another video.
Throws ErrNotReady if no file has been opened.
video.pos
• function pos() → Number
• function pos(ms) → Number
Without arguments, returns the position in the current file when playing, or the current length of the video when recording. The value is measured in milliseconds form the start.
With one argument, set the playing position to ms milliseconds.
Throws ErrNotReady if no file has been opened or created. With one argument, throws ErrInUse if a file is being played, or ExcWrongParamCount if a file is being recorded.
// Open a file and play seconds 5 to 12
video.open('sample.mp4');
video.pos(5000);
video.play();
sleep(7000);
video.stop();
print video.pos()
→ 11600
|
video.record
• function record(gain=100) → null
Starts or continues recording the current video file. gain is the audio recording gain, a number between 0 (minimum) and 100 (maximum). Default gain is 100. Setting the gain to a negative value sets it to 0, setting it to a value greater than 100 sets it to 100.
This function immediately returns, before recording completes. Exceptions can therefore be thrown anywhere in the following code. Use video.stop to pause recording, or video.wait to wait for recording reaching the maximum video size.
Throws ErrInUse if the video unit is busy playing or recording another video.
Throws ErrNotReady if video.create or video.setup have not been called.
// record video for twenty seconds
video.record();
sleep(20000);
video.stop()
|
video.setup
• function setup(audio=true, frate=null, vtype=null, atype=null) → null
| | |
| Compatibility of function video.setup |
| Sony Ericsson UIQ3 phones: video and audio types cannot be set. |
|
Sets the video recorder up and enables recording. audio determines whether audio recording will be enabled (audio=true) or disabled (audio=false). If frate#null, this frame rate should be used instead of the default. If vtype#null, this video type (MIME type) should be used instead of the default. If atype#null, this audio type (four character code) should be used instead of the default.
Throws ErrNotReady if video.create has not been called. Throws ErrNotSupported if any configuration setting (audio, video/audio type, frame size or frame rate) is not supported by the selected format (the frame size is configured at the very beginning via cam.on).
// setup for recording a silent MPEG-4 level 3 video
// at 30 frames per second
video.setup(false, 30,
"video/mp4v-es; profile-level-id=3");
// setup with default values, except for AMR audio
video.setup(true, null, null, " AMR");
|
video.show
• function show() → null
When playing, shows the last shown frame again. This can be useful if the video is stopped or paused and the screen has been changed otherwise, clearing or hiding the video display.
Throws ErrNotReady if no file has been opened.
See also video.hide.
video.stop
• function stop() → null
Stops (pauses) the currently playing video at the current position, without hiding it, or stops (pauses) recording. Does nothing if a video is neither played nor recorded.
Calling video.play after video.stop will continue playing.
Calling video.record after video.stop will continue recording.
video.volume
• function volume() → Number
• function volume(percent) → Number
Returns the current sound output volume and optionally changes it. The volume is a number between 0 (mute) and 100 (loudest). Default volume is 50. Setting the volume to a negative value sets it to 0, setting it to a value greater than 100 sets it to 100.
On most devices, changing the volume while a sound is playing has immediate effect.
v=video.play("c:\\documents\\video\\HomeBox.mp4");
while video.busy() do
sleep(100);
if video.pos()>v["len"]-2000 then
video.volume(video.volume()-5) // fade out
end
end
|
video.view
• function view() → Array
• function view(settings) → Array
| | |
| Compatibility of function video.view |
| Rotating the video is not supported on all devices | rot is ignored |
|
Gets or sets the source (video) and destination (screen) region settings for playing videos. Without an argument, returns the current settings. With one argument, sets the new settings according to the array elements found in settings, and returns the old settings.
Settings are specified as an array:
| Key | Meaning | Type |
| src | Video rectangle to show ([x,y,w,h]) | Array |
| dst | Screen rectangle to show video in ([x,y,w,h]) | Array |
| rot | Rotate the video by this times 90 degrees | Number |
| |
v=video.open('FasterThanMyShadow.mp4');
// squeeze the video into the upper left quadrant
view=video.view();
view['dst'][2]=v['size'][0] / 2;
view['dst'][3]=v['size'][1] / 2;
video.view(view);
// show only the upper half of the video
r=[0,0,v['size'][0],v['size'][1]/2];
view.view(['src':r,'dst':r])
|
video.wait
• function wait() → null
| | |
| Compatibility of function video.wait |
| Sony Ericsson UIQ3 phones: video.wait never returns when recording. |
|
Waits until playing completes, or recording completes (e.g. because the maximum size has been reached). Returns immediately if no video is playing or recording.
This function checks only the current m process: it will return immediately if a video is played or recorded by another process (inside or outside of m).
video Constants
• const recorders = Array
The list of available recorders with their supported formats and MIME types. Each recorder has the following fields:
| Key | Meaning | Type |
| name | The name of the recorder | String |
| supplier | The supplier of the recorder | String |
| formats | The formats supported by the recorder | Array |
| |
Each format has the following fields:
| Key | Meaning | Type |
| name | The name of the format | String |
| supplier | The supplier of the format | String |
| types | The MIME types supported by the format | Array |
| |
Note that the MIME types listed in the formats need not coincide with the MIME types returned by video.create.
for r in video.recorders do
print r["name"],"by",r["supplier"];
for f in r["formats"] do
print " ",f["name"],"by",r["supplier"];
for t in f["types"] do
print " ",t
end
end
end
→ Camcorder controller by Nokia
3GPP File Format by Nokia
video/3gpp
3GPP2 File Format by Nokia
video/3gpp2
&nb
|
Next: Telephony© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
