sys/man/7/playlistfs

   1 .TH PLAYLISTFS 7
   2 .SH NAME
   3 playlistfs \- playlist file system
   4 .SH SYNOPSIS
   5 .B games/playlistfs
   6 [
   7 .B \-s
   8 .I postname
   9 ]
  10 [
  11 .B \-m
  12 .I mountpoint
  13 ]
  14 [
  15 .B \-a
  16 ]
  17 .SH DESCRIPTION
  18 .B Playlistfs
  19 implements an audio player which plays files from a built-in play list.
  20 The player is controlled through three files, usually mounted at
  21 .BR /mnt .
  22 The files are
  23 .B /playctl
  24 for controlling play: start, stop, pause, skip, etc.;
  25 .B /playvol
  26 for controlling the playout volume; and
  27 .B /playlist
  28 for controlling the play list itself.
  29 .PP
  30 All three files can be written to control the player and read to obtain player
  31 status information.
  32 .PP
  33 When read, the files report the current status of the player, volume and playlist,
  34 respectively.  End of file is indicated by a read that returns zero bytes, as usual.
  35 However, in all three files, subsequent read operations will block until the status
  36 of the file changes and then report the changed state.  When the changed state has
  37 been read, another end-of-file indication is given, after which another read
  38 can be issued to wait for state changes.
  39 .PP
  40 The
  41 .B /playctl
  42 file returns strings of the form `\f2cmd n\fP'
  43 where
  44 .I cmd
  45 is one of
  46 .IR stop ,
  47 .IR pause ,
  48 or
  49 .I play
  50 and
  51 .I n
  52 is an index (or offset) into the playlist; indices start at zero.
  53 .PP
  54 The commands that can be written to
  55 .B /playctl
  56 take the same form; however, the index is an optional argument.  If the
  57 index is omitted, the current value is used. The commands are
  58 .IR play ,
  59 .IR stop ,
  60 .IR pause ,
  61 .IR resume ,
  62 and
  63 .IR skip .
  64 .I Play
  65 starts playing at the index.
  66 .I Stop
  67 stops playing.  If an index is given, the current index is set to it and
  68 can be used in future commands.
  69 .I Pause
  70 and
  71 .I Resume
  72 interrupt and continue play, respectively.  The index argument is always ignored and
  73 the whole command is ignored if the state in which they occur does not
  74 make sense.
  75 .I Skip
  76 adds the argument to the current index (adds one if no argument is given)
  77 and starts play at that index, stopping current play, if necessary.
  78 .PP
  79 Reads of
  80 .B /playvol
  81 return strings of the form
  82 .BR "`volume \f2n\fP'" ,
  83 where
  84 .I n
  85 is a number or, if there is more than one channel, a quoted set of numbers, between 0
  86 (minimum) and 100 (maximum).
  87 Writes to
  88 .B /playvol
  89 take the same form.
  90 .PP
  91 The
  92 .B /playlist
  93 file is an append-only file which accepts lines with one or two fields
  94 per line (parsed using
  95 .BR tokenize ).
  96 The first, compulsory, field is a file name, the optional second argument
  97 may contain a reference to, or a description of, the item, for instance in a graphical
  98 user interface.
  99 .B /playlist
 100 is append-only, individual lines cannot be removed.  However, the playlist
 101 can be cleared by opening the file with the
 102 .B OTRUNC
 103 flag.  A process that has
 104 .B /playlist
 105 open while the file is truncated will receive an error on the next read with
 106 .B errstr
 107 set to
 108 .IR "reading past eof" .
 109 When this error occurs, clients can seek to the beginning of the file and reread its contents.
 110 .PP
 111 After starting up,
 112 .B Playlistfs
 113 puts itself in the background. When called with the
 114 .B \-s
 115 flag, it posts a mountable file descriptor in
 116 .BR /srv/playlist.\f2postname\fP .
 117 The
 118 .B \-m
 119 flag can be used to specify a mount point other than
 120 .BR /mnt .
 121 .PP
 122 .B Playlistfs
 123 uses the
 124 .IR audio (1)
 125 decoders by running
 126 .IR play (1)
 127 for format detection and conversion to pcm.
 128 .SH FILES
 129 .BR /srv/playlistfs.\f2user\fP :
 130 default
 131 .B playlistfs
 132 mountable file descriptor used by juke(7).
 133 .br
 134 .BR /mnt/playctl :
 135 Control file
 136 .br
 137 .BR /mnt/playlist :
 138 Playlist file
 139 .br
 140 .BR /mnt/playvol :
 141 Volume control file
 142 .SH SOURCE
 143 .B /sys/src/games/music/playlistfs
 144 .SH SEE ALSO
 145 .IR play (1),
 146 .IR audio (1),
 147 .IR juke (7).