playlistfs 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  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. The files to be played are recognized by one of four extensions, and an appropriate
  123. player is then selected to play them. Files without a recognized extension are played by the
  124. .I pac
  125. player:
  126. .TP
  127. \&.mp3
  128. /bin/games/mp3dec
  129. .TP
  130. \&.pac
  131. /bin/games/pac4dec
  132. .TP
  133. \&.pcm
  134. /bin/cp
  135. .TP
  136. \&.ogg
  137. /bin/games/vorbisdec
  138. .SH FILES
  139. .BR /srv/playlistfs.\f2user\fP :
  140. default
  141. .B playlistfs
  142. mountable file descriptor used by juke(7).
  143. .br
  144. .BR /mnt/playctl :
  145. Control file
  146. .br
  147. .BR /mnt/playlist :
  148. Playlist file
  149. .br
  150. .BR /mnt/playvol :
  151. Volume control file
  152. .SH SOURCE
  153. .B /sys/src/games/music/playlistfs
  154. .SH SEE ALSO
  155. .IR juke (7),
  156. .IR audio (7)