19. Bigloo A ``practical Scheme compiler'' User manual for version 3.2a January 2009 -- Multimedia library

main page

top: | Bigloo A ``practical Scheme compiler'' User manual for version 3.2a January 2009

Multimedia library

Chapters

Bigloo provides various facilities for programming multimedia applications. It provides functions for parsing images and sounds and functions for controlling music players. All the functions, variables, and classes presented in the document are accessible via the `multimedia` library. Here is an example of module that uses this library:

    ;; Extract the thumbnail of a digital photography.
    (module thumbnail
       (library multimedia)
       (main main))

    (define (main argv)
       (when (and (pair? (cdr argv)) (file-exists? (cadr argv)))
          (let ((ex (jpeg-exif (cadr argv))))
              (when (exif? ex)
                 (display (exif-thumbnail ex))))))

### 19.1 Photography

The multimedia library provides functions for accessing the metadata generated by digital camera.

jpeg-exif file-name | Bigloo Multimedia procedure

The function `jpeg-exif` extracts the EXIF (http://en.wikipedia.org/wiki/Exif) metadata of a JPEG file as created by digital camera. The argument `file-name` is the name of the JPEG file. If the file contains an EXIF section it is returned as an instance of the `exif` class. Otherwise, this function returns `#f`.

jpeg-exif-comment-set! file-name text | Bigloo Multimedia procedure

Set the comment of the EXIF metadata section of the file file-name to `text`.

exif | Bigloo Multimedia class

    (class exif
       (version (default #f))
       (jpeg-encoding (default #f))
       (jpeg-compress (default #f))
       (comment (default #f))
       (commentpos (default #f))
       (commentlen (default #f))
       (date (default #f))
       (make (default #f))
       (model (default #f))
       (orientation (default 'landscape))
       (width (default #f))
       (height (default #f))
       (ewidth (default #f))
       (eheight (default #f))
       (xresolution (default #f))
       (yresolution (default #f))
       (resolution-unit (default #f))
       (focal-length (default #f))
       (flash (default #f))
       (fnumber (default #f))
       (iso (default #f))
       (shutter-speed-value (default #f))
       (exposure-time (default #f))
       (exposure-bias-value (default #f))
       (aperture (default #f))
       (metering-mode (default #f))
       (cdd-width (default #f))
       (focal-plane-xres (default #f))
       (focal-plane-units (default #f))
       (thumbnail (default #f))
       (thumbnail-path (default #f))
       (thumbnail-offset (default #f))
       (thumbnail-length (default #f)))

The instance of the `exif` class maps the EXIF metadata found in JPEG files into Bigloo objects. Since all fields are optional they are untyped.

### 19.2 Music

The multimedia library provides an extensive set of functions for dealing with music. It provides functions for accessing the metadata of certain music file formats, it provides functions for controlling the volume of the hardware mixers and it provides functions for playing and controlling music playback.

### 19.2.1 Metadata and Playlist

read-m3u input-port | Bigloo Multimedia procedure

write-m3u list output-port | Bigloo Multimedia procedure

The function `read-m3u` reads a playlist expressed in the M3U format from `input-port` and returns a list of songs. The function `write-m3u` encode such a list encoded in the M3U format to an output port.

mp3-id3 file-name | Bigloo Multimedia procedure

Extracts the ID3 tag of MP3 file named `file-name`. If the file contains an ID3 section, this function returns an instance of the Bigloo class `id3`. Otherwise, it returns `#f`. This function is able to deal with all the versions of ID3 encoding.

id3 | Bigloo Multimedia class

    (class id3
       version::bstring
       (title::bstring read-only)
       (artist::bstring read-only)
       (orchestra::obj read-only (default #f))
       (conductor::obj read-only (default #f))
       (interpret::obj read-only (default #f))
       (album::bstring read-only)
       (year::int read-only)
       (recording read-only (default #f))
       (comment::bstring read-only)
       (genre::bstring read-only)
       (track::int (default -1))
       (cd::obj (default #f)))

This class is used to reify the ID3 metadata used in the MP3 format.

### 19.2.2 Mixer

Bigloo proposes various functions and classes for controlling the audio volume of sound cards.

mixer | Bigloo Multimedia class

    (class mixer
       (devices::pair-nil (default '())))

The field `devices` is a list of available channels.

mixer-close mix | Bigloo Multimedia procedure

Closes a mixer. The argument `mix` must be an instance of the `mixer` class.

mixer-volume-get mix channel | Bigloo Multimedia procedure

mixer-volume-set! mix channel leftv rightv | Bigloo Multimedia procedure

The function `mixer-volume-get` returns the left and right volume levels (two values) of the `channel` of the mixer `mix`. The `channel` is denoted by its name and is represented as a string of characters. The argument `mix` is an instance of the `mixer` class.
The function `mixer-volume-set!` changes the audio level of a mixer channel.

soundcard::mixer | Bigloo Multimedia class

    (class soundcard::mixer
       (device::bstring read-only))

The instances of the class `soundcard`, a subclass of the `mixer` class, are used to access physical soundcard as supported by operating systems. The class field `device` stands for the name of the system device (e.g., `"/dev/mixer"` for the Linux OS). During the initialization of the instance, the device is opened and initialized.

### 19.2.3 Playback

Bigloo supports various functions for playing music. These functions rely on two data structure: music players and music status. The first ones are used to control player back-ends. The second ones are used to get information about the music being played. The following example shows how a simple music player using either MPlayer, MPG123, or MPC can be programmed with Bigloo.

    (module musicplay
       (library multimedia)
       (main main))

    (define (main args)
       (let ((files '())
    	 (backend 'mplayer)
    	 (command #f))
          (args-parse (cdr args)
    	 (("--mpg123" (help "Select the mpg123 back-end"))
    	  (set! backend 'mpg123))
    	 (("--mpc" (help "Select the mpc back-end"))
    	  (set! backend 'mpc))
    	 (("--mplayer" (help "Select the mplayer back-end"))
    	  (set! backend 'mplayer))
    	 (("--command" ?cmd (help "Set the command path"))
    	  (set! command cmd))
    	 (("--help" (help "This help"))
    	  (print "usage: music [options] file ...")
    	  (args-parse-usage #f)
    	  (exit 0))
    	 (else
    	  (set! files (cons else files))))
          ;; create a music player
          (let ((player (case backend
    		       ((mpg123)
    			(if command
    			    (instantiate::mpg123
    			       (path command))
    			    (instantiate::mpg123)))
    		       ((mplayer)
    			(if command
    			    (instantiate::mplayer
    			       (path command))
    			    (instantiate::mplayer)))
    		       ((mpc)
    			(instantiate::mpc)))))
             ;; fill the music play list
    	 (for-each (lambda (p) (music-playlist-add! player p)) (reverse files))
             ;; start playing
    	 (music-play player)
             ;; run an event loop with call-backs associated to some events
    	 (music-event-loop player
                :onstate (lambda (status)
    			(with-access::musicstatus status (state song volume)
    			   (print "state   : " state)
    			   (print "song    : " song)))
    	    :onmeta (lambda (meta playlist)
    		       (print "meta    : " meta)
    		       (print "playlist: ")
    		       (for-each (lambda (s) (print "        " s)) playlist))
    	    :onvolume (lambda (volume)
    		       (print "volume  : " volume))))))

music | Bigloo Multimedia abstract class

    (abstract-class music
       (frequency::long (default 2000000))

This abstract class is the root class of all music players.

musicproc::music | Bigloo Multimedia class

    (class musicproc::music
       (charset::symbol (default 'ISO-LATIN-1)))

This class is used to reify player that are run in an external process.

mplayer::musicproc | Bigloo Multimedia class

    (class mplayer::musicproc
       (path::bstring read-only (default "mplayer"))
       (args::pair-nil read-only (default '("-vo" "null" "-quiet" "-slave" "-idle")))
       (ao::obj read-only (default #unspecified))
       (ac::obj read-only (default #unspecified)))

A player based on the external software `MPlayer`. Creating such a player spawns in background a MPlayer process.

mpg123::musicproc | Bigloo Multimedia class

    (class mpg123::musicproc
       (path::bstring read-only (default "mpg123"))
       (args::pair-nil read-only (default '("--remote"))))

A player based on the external software `mpg123`.

mpc::music | Bigloo Multimedia class

    (class mpc::music
       (hello read-only (default #f))
       (host read-only (default "localhost"))
       (port read-only (default 6600))
       (timeout read-only (default 10008993))
       (prefix (default #f)))

A MPC client.

- `hello`: an optional string written when the connection is establish with the MPD server.
- `prefix`: an optional path prefix to be removed from music playlist. This is needed because MPD can only play music files registered in is private database. The file names used by MPD are relative a root directory used to fill the database. The `prefix` field allows programmer to write portable code that manages play list file names independently of the player selected.

musicstatus | Bigloo Multimedia class

    (class musicstatus
       (state::symbol (default 'stop))
       (volume::obj (default -1))
       (repeat::bool (default #f))
       (random::bool (default #f))
       (playlistid::int (default -1))
       (playlistlength::int (default 0))
       (xfade::int (default 0))
       (song::int (default 0))
       (songid::int (default 0))
       (songpos (default 0))
       (songlength::int (default 0))
       (bitrate::int (default 0))
       (khz::int (default 0))
       (err::obj (default #f)))

The instances of the class `musicstatus` denote that state of a player.

music-close music | Bigloo Multimedia procedure

music-reset! music | Bigloo Multimedia procedure

music-closed? music | Bigloo Multimedia procedure

Closes, resets, and tests the state of a music player.

music-playlist-get music | Bigloo Multimedia procedure

music-playlist-add! music song | Bigloo Multimedia procedure

music-playlist-delete! music int | Bigloo Multimedia procedure

music-playlist-clear! music | Bigloo Multimedia procedure

These functions controls the playlist used by a player.
Note: The `song` argument is an UTF8 encoded string (see Section Unicode (UCS-2) Strings) whatever the local file system encoding is. The function `music-playlist-get` returns a list of UTF8 encoded names.

- `music-playlist-get`: returns the list of songs (UTF8 names) of the current playlist.
- `music-playlist-add!`: adds an extra song (UTF8 name) at the end of the playlist.
- `music-delete!`: removes the song number `int` from the playlist.
- `music-clear!`: erases the whole playlist.

music-play music [song] | Bigloo Multimedia procedure

music-seek music time [song] | Bigloo Multimedia procedure

music-stop music | Bigloo Multimedia procedure

music-pause music | Bigloo Multimedia procedure

music-next music | Bigloo Multimedia procedure

music-prev music | Bigloo Multimedia procedure

These functions changes the state of the music player. The function `music-seek` seeks the playback position to the position `time`, which is an integer denoting a number of seconds.

music-crossfade music int | Bigloo Multimedia procedure

music-random-set! music bool | Bigloo Multimedia procedure

music-repeat-set! music bool | Bigloo Multimedia procedure

These functions controls how songs playback should follow each other.

music-volume-get music | Bigloo Multimedia procedure

music-volume-set! music vol | Bigloo Multimedia procedure

Get and set the audio volume of a player. Some player use the native mixer supported by the operating system some others use a software mixer unrelated to the hardware.

music-status music | Bigloo Multimedia procedure

music-update-status! music status | Bigloo Multimedia procedure

The function `music-status` returns an instance of the `musicstatus` class which denotes the state of the player. The function `music-update-status!` updates this status.

music-song music | Bigloo Multimedia procedure

music-songpos music | Bigloo Multimedia procedure

These two functions return the number of the song being played and the position in the song. These functions are somehow redundant with the function `music-status` because the status also contains information about the playback song and playback position. However, for some players getting the music song and the playback position is cheaper than getting the whole player status.

music-meta music | Bigloo Multimedia procedure

Returns the metadata the current song.

music-reset-error! music | Bigloo Multimedia procedure

Reset the previous errors detected by a player.

music-event-loop music [:onstate] [:onmeta] [:onerror] [:onvolume] | Bigloo Multimedia procedure

The function `music-event-loop` enable event notifications when the state of a player changes. The keyword arguments are:

- `:onstate`, a function of one parameter. When the player state changes, this function is called with an instance of `musicstatus` as actual parameter.
- `:onmeta`, a function of two parameters. This function is called when a metadata is detected in the music currently played.
- `:onerror`, a function of one parameter, invoked when an error is detected.
- `:onvolume`, a function of one parameter, invoked when the volume changes.

### 19.2.4 Music Player Daemon

Music Player Daemon (MPD in short) allows remote access for playing music http://www.musicpd.org. MPD is designed for integrating a computer into a stereo system that provides control for music playback over a local network. The Bigloo class `mpc` implements a `mpd` client. All Bigloo players can be access via the MPD protocol, using the
The following example shows how to access a MPlayer music player using the MPD protocol with a simple Bigloo program:

    (module mpd
       (library multimedia pthread)
       (main main))

    (define (main argv)
       (let ((db (instantiate::mpd-database
    		(directories (cdr argv))))
    	 (serv (make-server-socket 6600))
    	 (music (instantiate::mplayer)))
          (let loop ()
    	 (thread-start! (make-mpd-connection-thread music db sock))
    	 (loop))))

    (define (make-mpd-connection-thread music db sock)
       (instantiate::pthread
          (body (lambda ()
    	       (let ((pi (socket-input sock))
    		     (po (socket-output sock)))
    		  (input-timeout-set! pi 10000)
    		  (output-timeout-set! po 10000)
    		  (unwind-protect
    		     (mpd music pi po db)
    		     (socket-close sock)))))))

mpd music input-port output-port database [:log] | Bigloo Multimedia procedure

The function `mpd` implements a MPD server. It reads commands from the `input-port` and write results to `output-port`. The argument `database`, an instance of the `mpd-database` class, describes the music material that can be delivered by this player.

mpd-database | Bigloo Multimedia class

    (class mpd-database
       (directories::pair-nil read-only)

The field `directories` contains the list of the directories that contains music files.

This Html page has been produced by Skribe.
Last update Tue Jan 6 18:43:50 2009.