auplayer.1 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  1. .Dd Jul 5, 2018
  2. .Dt AUPLAYER 1
  3. .Os
  4. .Sh NAME
  5. .Nm auplayer
  6. .Nd a CLI for playing audio files
  7. .Sh SYNOPSIS
  8. .Nm
  9. .Op Fl lprsv
  10. .Op Fl F Ar file-descriptor
  11. .Op Fl I Ar file-descriptor
  12. .Op Fl b Ar buffer-size
  13. .Op Fl c Ar command
  14. .Op Fl d Ar device
  15. .Op Fl f Ar file-list
  16. .Op Fl g Ar file-list
  17. .Op Fl h Ar history-size
  18. .Op Fl i Ar input-file
  19. .Ar arg ...
  20. .Sh DESCRIPTION
  21. .Nm
  22. provides a simple command-line interface for playing audio files.
  23. .Pp
  24. The arguments are as follows:
  25. .Bl -tag -width Ds
  26. .It Fl F Ar file-descriptor
  27. Add lines read from
  28. .Ar file-descriptor
  29. to the playlist as below, removing leading & trailing white-space.
  30. .It Fl I Ar file-descriptor
  31. Read commands from
  32. .Ar file-descriptor
  33. instead of the standard input.
  34. .It Fl b Ar buffer-size
  35. Specify the buffer size for
  36. .Xr auopen 1 .
  37. .br
  38. Additionally, append
  39. .Qq Fl b Ar buffer-size
  40. to the end of the shell command string.
  41. .It Fl c Ar command
  42. Specify the shell command to execute when playing audio.
  43. .sp
  44. If
  45. .Ar command
  46. is empty then
  47. .Nm
  48. does not try to play files, does not look-up files when using the
  49. .Sy a
  50. command, and does not exit if there are no more entries available.
  51. .br
  52. This is to aid in testing.
  53. .It Fl d Ar device
  54. Append
  55. .Qq Fl d Ar device
  56. to the end of the shell command string.
  57. .It Fl f Ar file-list
  58. Add each line of
  59. .Ar file-list
  60. to the playlist as below, removing leading & trailing white-space. If
  61. .Ar file-list
  62. is
  63. .Qq -
  64. then the standard input is read instead.
  65. .It Fl g Ar file-list
  66. .Xr glob 3
  67. each line of
  68. .Ar file-list ,
  69. after removing the leading & trailing white-space, adding the results to
  70. the playlist as below. If
  71. .Ar file-list
  72. is
  73. .Qq -
  74. then the standard input is read instead.
  75. .It Fl h Ar history-size
  76. Specify the number of elements to keep in history.
  77. .It Fl l
  78. After playing the last file loop back to the beginning instead of
  79. exiting, reshuffling if
  80. .Fl s
  81. is specified. This option has no effect if
  82. .Fl r
  83. is specified.
  84. .It Fl i Ar input
  85. Read commands from
  86. .Ar input
  87. instead of the standard input.
  88. .It Fl p
  89. Have
  90. .Nm
  91. behave in a manner suitable for being controlled by another program.
  92. .Pp
  93. .Nm
  94. will print information in a parse friendly format:
  95. .Bl -tag -width Ds
  96. .It Sy : Ar time Sy / Op Ar total
  97. The current position and total length of the current file. For example:
  98. .Qq : 0:12:34.56/1:23:45.67 .
  99. .It Sy ! Ar string
  100. Information about the internal state. For example
  101. .Qq !pause
  102. and
  103. .Qq !unpause .
  104. .It Sy @ Ar path
  105. The path of the currently playing entry.
  106. .It Sy + Ar path
  107. The specified path was appended to the playlist.
  108. .It Sy - Ar path
  109. The specified path was removed from the playlist.
  110. .El
  111. .Pp
  112. This option supersedes
  113. .Fl v .
  114. .It Fl r
  115. Play the audio files in a random order.
  116. .It Fl s
  117. Shuffle the list of audio files.
  118. .It Fl v
  119. Enable verbose output.
  120. .It Ar \&(
  121. Begin an ordered sub-group.
  122. .It Ar (r
  123. Begin a random sub-group.
  124. Random sub-groups play one random entry each time it is selected.
  125. Trailing characters are ignored.
  126. .It Ar (s
  127. Begin a shuffled sub-group.
  128. Trailing characters are ignored.
  129. .It Ar \&)
  130. End a sub-group list.
  131. .It Ar file
  132. Append
  133. .Ar file
  134. to the list of files. If it is a directory, non-recursively append its,
  135. sorted, entries to the list of files.
  136. .El
  137. .Pp
  138. If no input is selected, and the standard input was specified by
  139. .Fl f ,
  140. then the input will be read from
  141. .Qq /dev/tty .
  142. However, the
  143. .Fl p
  144. option will cause an error to be produced instead.
  145. .Sh COMMANDS
  146. Commands have the following global syntax:
  147. .Pp
  148. .Op count
  149. .Li c
  150. .Op argument
  151. .Pp
  152. Where
  153. .Sy c
  154. is the command character.
  155. .Pp
  156. The available commands are as follows:
  157. .Bl -tag -width Ds
  158. .It Sy \&(
  159. Begins a sub-group as above.
  160. .Ar count
  161. is ignored.
  162. .It Sy \&)
  163. Ends a sub-group as above. Both
  164. .Ar count
  165. and
  166. .Ar argument
  167. are ignored.
  168. .It Sy +
  169. Seek forwards by
  170. .Ar argument .
  171. .Ar count
  172. is ignored.
  173. .It Sy -
  174. Seek backwards by
  175. .Ar argument .
  176. .Ar count
  177. is ignored.
  178. .It Sy =
  179. Seek to the time specified by
  180. .Ar argument .
  181. If
  182. .Ar argument
  183. is negative the seek is relative to the end of the file.
  184. .Ar count
  185. is ignored.
  186. .It Sy ?
  187. Print the current file, the position in it, and its length. Both
  188. .Ar count
  189. and
  190. .Ar argument
  191. are ignored.
  192. .It Sy /
  193. Search forward for
  194. .Ar argument
  195. and move to the matching entry, if any.
  196. .Ar count
  197. is ignored.
  198. .It Sy L
  199. Toggle looping. Both
  200. .Ar count
  201. and
  202. .Ar argument
  203. are ignored.
  204. .It Sy V
  205. Toggle verbosity. Both
  206. .Ar count
  207. and
  208. .Ar argument
  209. are ignored.
  210. .It Sy a
  211. Append files matched by
  212. .Ar argument
  213. to the file list.
  214. .Ar count
  215. is ignored.
  216. .It Sy d
  217. If an argument is given, remove any entries that match
  218. .Ar argument ,
  219. otherwise remove the current entry.
  220. .Ar count
  221. is ignored.
  222. .It Sy h
  223. Go back
  224. .Ar count
  225. entries.
  226. .Ar argument
  227. is ignored.
  228. .It Sy i
  229. A synonym for
  230. .Sy ? .
  231. .It Sy j
  232. A synonym for
  233. .Sy h .
  234. .It Sy k
  235. Go forward
  236. .Ar count
  237. entries.
  238. .Ar argument
  239. is ignored.
  240. .It Sy l
  241. A synonym for
  242. .Sy k .
  243. .It Sy p
  244. Toggle the pause state. Both
  245. .Ar count
  246. and
  247. .Ar argument
  248. are ignored.
  249. .It Sy q
  250. Exit
  251. .Nm .
  252. Both
  253. .Ar count
  254. and
  255. .Ar argument
  256. are ignored.
  257. .It Sy r
  258. Replay the current entry. Both
  259. .Ar count
  260. and
  261. .Ar argument
  262. are ignored.
  263. .El
  264. .Sh EXIT STATUS
  265. .Ex -std
  266. .Sh SEE ALSO
  267. .Xr auopen 1
  268. .Xr au2dev 1
  269. .Xr glob 3