PLAYLISTFS(7)                                       PLAYLISTFS(7)

     NAME
          playlistfs - playlist file system

     SYNOPSIS
          games/playlistfs [ -s postname ] [ -m mountpoint ] [ -a ]

     DESCRIPTION
          Playlistfs implements an audio player which plays files from
          a built-in play list.  The player is controlled through
          three files, usually mounted at /mnt.  The files are
          /playctl for controlling play: start, stop, pause, skip,
          etc.; /playvol for controlling the playout volume; and
          /playlist for controlling the play list itself.

          All three files can be written to control the player and
          read to obtain player status information.

          When read, the files report the current status of the
          player, volume and playlist, respectively.  End of file is
          indicated by a read that returns zero bytes, as usual.  How-
          ever, in all three files, subsequent read operations will
          block until the status of the file changes and then report
          the changed state.  When the changed state has been read,
          another end-of-file indication is given, after which another
          read can be issued to wait for state changes.

          The /playctl file returns strings of the form `cmd n' where
          cmd is one of stop, pause, or play and n is an index (or
          offset) into the playlist; indices start at zero.

          The commands that can be written to /playctl take the same
          form; however, the index is an optional argument.  If the
          index is omitted, the current value is used. The commands
          are play, stop, pause, resume, and skip. Play starts playing
          at the index.  Stop stops playing.  If an index is given,
          the current index is set to it and can be used in future
          commands.  Pause and Resume interrupt and continue play,
          respectively.  The index argument is always ignored and the
          whole command is ignored if the state in which they occur
          does not make sense.  Skip adds the argument to the current
          index (adds one if no argument is given) and starts play at
          that index, stopping current play, if necessary.

          Reads of /playvol return strings of the form `volume n',
          where n is a number or, if there is more than one channel, a
          quoted set of numbers, between 0 (minimum) and 100 (maxi-
          mum).  Writes to /playvol take the same form.

          The /playlist file is an append-only file which accepts
          lines with one or two fields per line (parsed using

     PLAYLISTFS(7)                                       PLAYLISTFS(7)

          tokenize).  The first, compulsory, field is a file name, the
          optional second argument may contain a reference to, or a
          description of, the item, for instance in a graphical user
          interface.  /playlist is append-only, individual lines can-
          not be removed.  However, the playlist can be cleared by
          opening the file with the OTRUNC flag.  A process that has
          /playlist open while the file is truncated will receive an
          error on the next read with errstr set to reading past eof.
          When this error occurs, clients can seek to the beginning of
          the file and reread its contents.

          After starting up, Playlistfs puts itself in the background.
          When called with the -s flag, it posts a mountable file
          descriptor in /srv/playlist.postname.  The -m flag can be
          used to specify a mount point other than /mnt.

          Playlistfs uses the audio(1) decoders by running play(1) for
          format detection and conversion to pcm.

     FILES
          /srv/playlistfs.user: default playlistfs mountable file
          descriptor used by juke(7).
          /mnt/playctl: Control file
          /mnt/playlist: Playlist file
          /mnt/playvol: Volume control file

     SOURCE
          /sys/src/games/music/playlistfs

     SEE ALSO
          play(1), audio(1), juke(7).