<doc> MULTIMEDIA library
<library> Multimedia

== Description ==

This document describes facilities provided by HOP for programming
Multimedia Web applications.

~~ HOP 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:

<code>
  ;; Extract the thumbnail of a digital photography.
  (module thumbnail
     (library multimedia))
  
  (define-service (thumbnail photo)
     (when (file-exists? photo)
        (let ((ex (jpeg-exif photo)))
            (when (exif? ex)
               (exif-thumbnail ex)))))
</code>

The source code of the 
[[http://hop.inria.fr/hop/weblets/homepage?weblet=hopmusic|HopMusic]] 
weblet is good example of Web Audio multimedia application implemented 
in Hop. It uses almost all the features described in the manual page.

== Examples ==

<example>music, exif, m3u</example>

== Synopsis ==

=== Server ===

  (class exif ...)
  (jpeg-exif file-name)
  (jpeg-exif-comment-set! file-name text)

  (read-m3u input-port)
  (write-m3u list input-port)

  (class id3 ...)
  (mp3-id3 file-name)

  (class mixer devices)
  (class soundcard::mixer device)
  (mixer-close mix)
  (mixer-volume-get mix channel)

  (class music frequency)
  (class musicproc::music charset)
  (class mplayer::musicproc path args ao ac)
  (class mpg123::musicproc path args)
  (class mpc::music hello host port timeout prefix)
  
  (class musicstatus ...)
  
  (music-close music)
  (music-reset! music)
  (music-closed? music)
  (music-playlist-get music)
  (music-playlist-add! music song)
  (music-playlist-delete! music int)
  (music-playlist-clear! music)
  (music-play music [song])
  (music-seek music time [song])
  (music-stop music)
  (music-pause music)
  (music-next music)
  (music-prev music)
  (music-crossfade music int)
  (music-random-set! music bool)
  (music-repeat-set! music bool)
  (music-volume-get music)
  (music-volume-set! music vol)
  (music-status music)
  (music-update-status! music status)
  (music-song music)
  (music-songpos music)
  (music-meta music)
  (music-reset-error! music)
  (music-event-loop music :ontstate :onmeta :onerror :onvolume)
  
  (mpd  music input-port output-port database :log)
  (class mpd-database directories)

  (hsv->rgb h s v)
  (hsl->rgb h s l)
  (rgb->hsv r g b)
  (rgb->hsl r g l)


== Server Definitions ==
<server>

=== Photography ===

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

==== ++(class exif ...)++ ====
<class> exif
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| version   |    r      |   obj    |  ++#f++    | exif version.    |
| jpeg-encoding   |    r      |   obj    |  ++#f++    |     |
| jpeg-compress   |    r      |   obj    |  ++#f++    |     |
| comment   |    r      |   obj    |  ++#f++    |     |
| commentpos   |    r      |   obj    |  ++#f++    |     |
| commentlen   |    r      |   obj    |  ++#f++    |     |
| date   |    r      |   obj    |  ++#f++    |     |
| make   |    r      |   obj    |  ++#f++    |     |
| model   |    r      |   obj    |  ++#f++    |     |
| orientation   |    r      |   symbol    |  ++landscape++    | The photograph orientation.    |
| width   |    r      |   obj    |  ++#f++    |     |
| height   |    r      |   obj    |  ++#f++    |     |
| ewidth   |    r      |   obj    |  ++#f++    |     |
| eheight   |    r      |   obj    |  ++#f++    |     |
| xresolution   |    r      |   obj    |  ++#f++    |     |
| yresolution   |    r      |   obj    |  ++#f++    |     |
| resolution-unit   |    r      |   obj    |  ++#f++    |     |
| focal-length   |    r      |   obj    |  ++#f++    |     |
| flash   |    r      |   obj    |  ++#f++    |     |
| fnumber   |    r      |   obj    |  ++#f++    |     |
| iso   |    r      |   obj    |  ++#f++    |     |
| shutter-speed-value   |    r      |   obj    |  ++#f++    |     |
| exposure-time   |    r      |   obj    |  ++#f++    |     |
| exposure-bias-value   |    r      |   obj    |  ++#f++    |     |
| aperture   |    r      |   obj    |  ++#f++    |     |
| metering-mode   |    r      |   obj    |  ++#f++    |     |
| cdd-width   |    r      |   obj    |  ++#f++    |     |
| focal-plane-xres   |    r      |   obj    |  ++#f++    |     |
| focal-plane-units   |    r      |   obj    |  ++#f++    |     |
| thumbnail   |    r      |   obj    |  ++#f++    |     |
| thumbnail-path   |    r      |   obj    |  ++#f++    |     |
| thumbnail-offset   |    r      |   obj    |  ++#f++    |     |
| thumbnail-length   |    r      |   obj    |  ++#f++    |     |
</fields>

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

</class>

==== ++(jpeg-exif file-name)++ ====
<function> jpeg-exif
<arguments>
^  arguments  ^   type          ^  short description           ^
| file-name   |  ::string       | a file name.                 |
</arguments>

The function ++jpeg-exif++ extracts the 
[[http://en.wikipedia.org/wiki/Exif|EXIF ]] metadata of a JPEG file as created
by digital camera. The argument @var{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++.
</function>

==== ++(jpeg-exif-comment-set! file-name text)++ ====
<function> jpeg-exif-comment-set!
<arguments>
^  arguments  ^   type          ^  short description           ^
| file-name   |  ::string       | a file name.                 |
| text   |  ::string       | a user comment.                 |
</arguments>
Set the comment of the EXIF metadata section of the file file-name
to ++text++.
</function>

=== 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.

==== Metadata and Playlist ====
===== ++(read-m3u input-port)++ =====
===== ++(write-m3u m3u output-port)++ =====
<function> read-m3u 
<function> write-m3u
<arguments>
^  arguments  ^   type          ^  short description           ^
| input-port   |  ::input-port       | an input port.                 |
| output-port   |  ::output-port       | an output port.                 |
| m3u   |  ::list       | a playlist.                 |
</arguments>

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.
</function>
</function> 

===== ++(mp3-id3 file-name)++ =====
<function> mp3-id3
<arguments>
^  arguments  ^   type          ^  short description           ^
| file-name   |  ::string       | a file name.                 |
</arguments>

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.

</function>

===== ++(class id3 ...)++ =====
<class> id3
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| version   |    r      |   string    |     | id3 version.    |
| title   |    r      |   string    |     |     |
| artist   |    r      |   string    |     |     |
| orchestra   |    r      |   obj    | ++#f++    |     |
| conductor   |    r      |   obj    | ++#f++    |     |
| interpret   |    r      |   obj    | ++#f++    |     |
| album   |    r      |   string    |     |     |
| year   |    r      |   string    |     |     |
| recording   |    r      |   obj    | ++#f++    |     |
| comment   |    r      |   string    |     |     |
| genre   |    r      |   string    |     |     |
| track   |    r      |   integer    | ++-1++    |     |
| cd   |    r      |   obj    | ++#f++    |     |
</fields>

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

</class>

==== Mixer ====

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

===== ++(class mixer ...)++ =====
<class> mixer
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| devices   |    r      |   list    |  ++()++   | The list of available channels.    |
</fields>
</class>

===== ++(class soundcard::mixer ..)++ =====
<class> soundcard
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| devices  |    r      |   string    |    |     |
</fields>

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.
</class>

===== ++(mixer-close mix)++ =====
<function> mixer-close
<arguments>
^  arguments  ^   type          ^  short description           ^
| mix   |  ::mixer       | The mixer.                 |
</arguments>

Closes a mixer. 
</function>

===== ++(mixer-volume-get mix channel)++ =====
===== ++(mixer-volume-set! mix channel leftv rightv)++ =====
<function> mixer-volume-get
<function> mixer-volume-set!
<arguments>
^  arguments  ^   type          ^  short description           ^
| mix   |  ::mixer       | The mixer.                 |
| channel   |  ::integer       | The channel number.                 |
| leftv   |  ::integer       | an integer in the range ++0..100++.                 |
| rightv   |  ::integer       | an integer in the range ++0..100++.                 |
</arguments>

The function ++mixer-volume-get++ returns the left and right volume
levels (two values) of the ++channel++ of the mixer ++mix++. The 
@var{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.
</function>
</function>

==== Playback ====

HOP 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 HOP.

===== ++(abstract-class music ...)++ =====
<class> music
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| frequency   |    r      |   long    |  ++2000000++   |     |
</fields>

This abstract class is the root class of all music players.
</class>

===== ++(abstract-class musicproc::music ...)++ =====
<class> musicproc
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| charset   |    r      |   symbol    |  ++ISO-LATIN-1++   |     |
</fields>

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

===== ++(class mplayer::musicproc ...)++ =====
<class> mplayer
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| path   |    r      |   string    |  ++mplayer++   | The binary path to MPLAYER.    |
| args   |    r      |   list    |  ++'("-vo" "null" "-quiet" "-slave" "-idle"))++   | The default argument list.  |
| ao    |     r     |  obj  | ++#unspecified++  | The MPlayer //ao// command line argument.  |
| ac    |     r     |  obj  | ++#unspecified++  | The MPlayer //ac// command line argument.  |
</fields>

A player based on the external software ++MPlayer++. Creating such a player
spawns in background a MPlayer process.
</class>

===== ++(class mpg123::musicproc ...)++ =====
<class> mplayer
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| path   |    r      |   string    |  ++mpg123++   | The binary path to MPLAYER.    |
| args   |    r      |   list    |  ++'("--remote"))++   | The default argument list.  |
</fields>

A player based on the external software ++mpg123++. Creating such a player
spawns in background a mpg123 process.
</class>

===== ++(class mpc::music ...)++ =====
<class> mpc
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| hello   |    r      |   obj    |  ++#f++   | An optional //hello// phrase sent to MPD.  |
| host   |    r      |   string    |  ++localhost++   | The default MPD host.  |
| port   |    r      |   integer    |  ++6600++   | The default MPD port.  |
| timeout   |    r      |   integer    |  ++10008993++   |   |
| prefix  |    r/w  | bool  |  ++#f++  |  |
</fields>

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.


</class>

===== ++(class musicstatus ...)++ =====
<class> musicstatus
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| state   |    r      |   symbol    |  ++stop++   |   |
| volume   |    r      |   obj    |  ++-1++   | |
| repeat   |    r      |   bool    |  ++#f++   | |
| random   |    r      |   bool    |  ++#f++   | |
| playlistid   |    r      |   integer    |  ++-1++   | |
| playlistlength   |    r      |   integer    |  ++0++   | |
| xfade   |    r      |   integer    |  ++0++   | |
| song   |    r      |   integer    |  ++0++   | |
| songid   |    r      |   integer    |  ++0++   | |
| songpos   |    r      |   integer    |  ++0++   | |
| songlength   |    r      |   integer    |  ++0++   | |
| bitrate   |    r      |   integer    |  ++0++   | |
| khz   |    r      |   integer    |  ++0++   | |
| err   |    r      |   obj    |  ++#f++   | |
</fields>

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

</class>

===== ++(music-close music)++ ====
===== ++(music-closed? music)++ ====
===== ++(music-reset! music)++ ====
<function> music-close
<function> music-closed?
<function> music-reset!
<arguments>
^  arguments  ^   type          ^  short description           ^
| music   |  ::music       | The music player.                 |
</arguments>
Closes, resets, and tests the state of a music player.
</function>
</function>
</function>

===== ++(music-playlist-get music)++ =====
===== ++(music-playlist-add! music song)++ =====
===== ++(music-playlist-delete! music int)++ =====
===== ++(music-playlist-clear! music)++ =====
<function> music-playlist-get
<function> music-playlist-add!
<function> music-playlist-delete!
<function> music-playlist-clear!
These functions controls the playlist used by a player. 

  * ++music-playlist-get++: returns the list of songs of the current 
 playlist.
  * ++music-playlist-add!++: adds an extra song at the end of the playlist.
  * ++music-delete!++: removes the song number ++int++ from the playlist.
  * ++music-clear!++: erases the whole playlist.


</function>
</function>
</function>
</function>

===== ++(music-play music [song])++ =====
===== ++(music-seek music time [song])++ =====
===== ++(music-stop music)++ =====
===== ++(music-pause music)++ =====
===== ++(music-next music)++ =====
===== ++(music-prev music)++ =====
<function> music-play
<function> music-seek
<function> music-stop
<function> music-pause
<function> music-next
<function> music-prev

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.
</function>
</function>
</function>
</function>
</function>
</function>

===== ++(music-crossfade music int)++ =====
===== ++(music-random-set! music bool)++ =====
===== ++(music-repeat-set! music bool)++ =====
<function> music-crossfade
<function> music-random-set!
<function> music-repeat-set!
These functions controls how songs playback should follow each other.
</function>
</function>
</function>

===== ++(music-volume-get music)++ =====
===== ++(music-volume-set! music vol)++ =====
<function> music-volume-get
<function> music-volume-set!
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.
</function>
</function>

===== ++(music-status music)++ =====
===== ++(music-update-status! music status)++ =====
<function> music-status
<function> music-update-status!
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.
</function>
</function>

===== ++(music-song music)++ =====
===== ++(music-songpos music)++ =====
<function> music-song
<function> music-songpos
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.
</function>
</function>

===== ++(music-meta music)++ =====
<function> music-meta
Returns the metadata the current song.
</function>

===== ++(music-reset-error! music)++ =====
<function> music-reset-error!
Reset the previous errors detected by a player.
</function>

===== ++(music-event-loop music [:onstate] [:onmeta] [:onerror] [:onvolume])++ =====
<function> music-event-loop

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.


</function>

==== MPD ====

[[http://www.musicpd.org|Music Player Daemon]] (MPD in short) allows 
remote access for playing music. 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 HOP program:

<code>
  (module mpd
     (library multimedia pthread))
     
  (define-service (mpd directory)
     (let ((db (instantiate::mpd-database
  		  (directories (list directory))))
  	   (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)))))))
</code>

===== ++(mpd music input-port output-port database [:log])++ =====
<function> mpd
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.
</function>

===== ++(class mpd-database directories)++ =====
<class> mpd-database
<fields>
^  fields  ^   access  ^   type      ^  default value     ^  short description           ^
| directories   |    r      |   list    |  ++()++   | The list of repositories.    |
</fields>

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

</class>

=== Color ===

===== ++(hsv->rgb h s v)++ =====
===== ++(hsl->rgb h s l)++ =====
===== ++(rgb->hsv r g b)++ =====
===== ++(rgb->hsl r g b)++ =====
<function> hsv->rgb
<function> hsl->rgb
<function> rgb->hsv
<function> rgb->hsl
</function>
</function>
</function>
</function>

These procedures converts from and to HSV, HSL, and RGB representations.
The argument ++h++ is an integer in the range ++[0..360]++, 
the arguments ++s++, ++v++, and ++l++ in the range ++[0..100]++. The
arguments ++r++, ++g++, and ++b++ are in the range ++[0..255]++.
These procedures returns multiple-values.

<code>
  (multiple-value-bind (r g b)
     (hsv->rgb 340 34 56)
     (list r g b)) ,(<SYM> '=>) (143 94 110)
  (multiple-value-bind (h s v)
     (rgb->hsv 255 0 0)
     (list h s v)) ,(<SYM> '=>) (0 100 100)
</code>

</server>
</library>
</doc>