Use upstream manpage for squeezelite
tony mancill
3 years ago
| 0 | .\" Hey, EMACS: -*- nroff -*- | |
| 1 | .\" (C) Copyright 2013-4 Chris Boot <bootc@debian.org> | |
| 2 | .\" | |
| 3 | .\" First parameter, NAME, should be all caps | |
| 4 | .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection | |
| 5 | .\" other parameters are allowed: see man(7), man(1) | |
| 6 | .TH SQUEEZELITE 1 "2016-01-30" "Debian Project" | |
| 7 | .\" Please adjust this date whenever revising the manpage. | |
| 8 | .\" | |
| 9 | .\" Some roff macros, for reference: | |
| 10 | .\" .nh disable hyphenation | |
| 11 | .\" .hy enable hyphenation | |
| 12 | .\" .ad l left justify | |
| 13 | .\" .ad b justify to both left and right margins | |
| 14 | .\" .nf disable filling | |
| 15 | .\" .fi enable filling | |
| 16 | .\" .br insert line break | |
| 17 | .\" .sp <n> insert n+1 empty lines | |
| 18 | .\" for manpage-specific macros, see man(7) | |
| 19 | .SH NAME | |
| 20 | squeezelite \- Lightweight headless Squeezebox emulator | |
| 21 | .SH SYNOPSIS | |
| 22 | .B squeezelite | |
| 23 | .RI [ options ] | |
| 24 | .SH DESCRIPTION | |
| 25 | .B Squeezelite | |
| 26 | is a small headless Logitech Squeezebox emulator. It is aimed at supporting high | |
| 27 | quality audio including USB DAC based output at multiple sample rates. | |
| 28 | .PP | |
| 29 | The player is controlled using, and media is streamed from, a Logitech Media | |
| 30 | Server instance running somewhere on the local network. | |
| 31 | .SH OPTIONS | |
| 32 | This program supports the following options: | |
| 33 | .TP | |
| 34 | .B \-? | |
| 35 | Show a summary of the available command-line options. | |
| 36 | .TP | |
| 37 | .B \-s <server>[:<port>] | |
| 38 | Connect to the specified Logitech Media Server, otherwise uses automatic | |
| 39 | discovery to find server on the local network. This option should only be needed | |
| 40 | if automatic discovery does not work, or the server is not on the local network | |
| 41 | segment (e.g. behind a router). | |
| 42 | .TP | |
| 43 | .B \-o <output device> | |
| 44 | Specify the audio output device; the default value is | |
| 45 | .IR default . | |
| 46 | Use the | |
| 47 | .B \-l | |
| 48 | option to list available output devices. | |
| 49 | .I - | |
| 50 | can be used to output raw samples to standard output. | |
| 51 | .TP | |
| 52 | .B \-l | |
| 53 | List available audio output devices to stdout and exit. These device names can | |
| 54 | be passed to the | |
| 55 | .B \-o | |
| 56 | option in order to select a particular device or configuration to use for audio | |
| 57 | playback. | |
| 58 | .TP | |
| 59 | .B \-a <params> | |
| 60 | Specify parameters used when opening an audio output device. | |
| 61 | For ALSA, the format | |
| 62 | .B <b>:<p>:<f>:<m> | |
| 63 | is used where | |
| 64 | .B <b> | |
| 65 | is the buffer time in milliseconds (values less than 500) or size in bytes (default | |
| 66 | .IR 40 ms); | |
| 67 | .B <p> | |
| 68 | is the period count (values less than 50) or size in bytes (default | |
| 69 | .IR 4 " periods);" | |
| 70 | .B <f> | |
| 71 | is the sample format (possible values: | |
| 72 | .IR 16 ", " 24 ", " 24_3 " or " 32 ); | |
| 73 | .B <m> | |
| 74 | is whether to use mmap (possible values: | |
| 75 | .IR 0 " or " 1 ). | |
| 76 | For PortAudio, the value is simply the target latency in milliseconds. When the | |
| 77 | output is sent to standard output, the value can be | |
| 78 | .IR 16 ", " 24 " or " 32 , | |
| 79 | which denotes the sample size in bits. | |
| 80 | .TP | |
| 81 | .B \-b <stream>:<output> | |
| 82 | Specify internal stream and output buffer sizes in kilobytes. | |
| 83 | .TP | |
| 84 | .B \-c <codec1>,... | |
| 85 | Restrict codecs to those specified, otherwise load all available codecs. Use | |
| 86 | .B squeezelite -h | |
| 87 | to obtain the list of codecs built into \fBsqueezelite\fR. | |
| 88 | .TP | |
| 89 | .B \-C <timeout> | |
| 90 | Close the output device after | |
| 91 | .B <timeout> | |
| 92 | seconds of the player being idle; the default is to always keep the device open | |
| 93 | as long as the payer is "on". | |
| 94 | .TP | |
| 95 | .B \-d <category>=<level> | |
| 96 | Set logging level. Categories are: | |
| 97 | .IR all ", " slimproto ", " stream ", " decode ", " output " or " ir . | |
| 98 | Levels can be: | |
| 99 | .IR info ", " debug " or " sdebug . | |
| 100 | The option can be repeated to set different log levels for different categories. | |
| 101 | .TP | |
| 102 | .B \-e <codec1>,... | |
| 103 | Explicitly exclude native support of one or more codecs. See also | |
| 104 | .BR \-c , | |
| 105 | above. | |
| 106 | .TP | |
| 107 | .B \-f <logfile> | |
| 108 | Send logging output to a log file instead of standard output or standard error. | |
| 109 | .TP | |
| 110 | .B \-i [<filename>] | |
| 111 | Enable LIRC remote control support. If the optional | |
| 112 | .B <filename> | |
| 113 | is not provided, | |
| 114 | .I ~/.lircrc | |
| 115 | is used instead. | |
| 116 | .TP | |
| 117 | .B \-m <mac addr> | |
| 118 | Override the player's MAC address. The format must be colon-delimited | |
| 119 | hexadecimal, for example: ab:cd:ef:12:34:56. This is usually automatically | |
| 120 | detected, and should not need to be provided in most circumstances. | |
| 121 | .TP | |
| 122 | .B \-M <modelname> | |
| 123 | Override the player's hardware model name. The default value is | |
| 124 | .IR SqueezeLite . | |
| 125 | .TP | |
| 126 | .B \-n <name> | |
| 127 | Set the player name. This name is used by the Logitech Media Server to refer to | |
| 128 | the player by name. This option is mututally exclusive with | |
| 129 | .BR \-N . | |
| 130 | .TP | |
| 131 | .B \-N <filename> | |
| 132 | Allow the server to set the player's name. The player name is stored in the file | |
| 133 | pointed to by | |
| 134 | .B <filename> | |
| 135 | so that it can persist between restarts. This option is mututally exclusive with | |
| 136 | .BR \-n . | |
| 137 | .TP | |
| 138 | .B \-p <priority> | |
| 139 | Set real time priority of output thread (1-99; default | |
| 140 | .IR 45 ). | |
| 141 | Not applicable when using PortAudio. | |
| 142 | .TP | |
| 143 | .B \-P <filename> | |
| 144 | Write the process ID (PID) number to the given | |
| 145 | .BR <filename> . | |
| 146 | This may be useful when running \fBsqueezelite\fR as a daemon. | |
| 147 | .TP | |
| 148 | .B \-r <rates>[:<delay>] | |
| 149 | Specify sample rates supported by the output device; this is required if the | |
| 150 | output device is switched off when \fBsqueezelite\fR is started. The format is | |
| 151 | either a single maximum sample rate, a range of sample rates in the format | |
| 152 | .IR <min> - <max> , | |
| 153 | or a comma-separated list of available rates. Delay is an optional time to wait | |
| 154 | when switching sample rates between tracks, in milliseconds. | |
| 155 | .TP | |
| 156 | .B \-u|-R [params] | |
| 157 | Enable upsampling of played audio. The argument is optional; see | |
| 158 | .B RESAMPLING | |
| 159 | (below) for more information. The options | |
| 160 | .BR -u " and " -R | |
| 161 | are synonymous. | |
| 162 | .TP | |
| 163 | .B \-D [delay] | |
| 164 | Output device supports DSD over PCM (DoP). DSD streams will be converted to DoP | |
| 165 | before output. If this option is not supplied, DSD streams will be converted to | |
| 166 | PCM and resampled, so they can be played on a PCM DAC. Delay is an optional time | |
| 167 | to wait when switching between PCM and DoP between tracks, in milliseconds. | |
| 168 | .TP | |
| 169 | .B \-v | |
| 170 | Enable visualiser support. This creates a shared memory segment that contains | |
| 171 | some of the audio being played, so that an external visualiser can read and | |
| 172 | process this to create visualisations. | |
| 173 | .TP | |
| 174 | .B \-L | |
| 175 | List available volume controls for the output device. Only applicable when | |
| 176 | using ALSA output. | |
| 177 | .TP | |
| 178 | .B \-U <control> | |
| 179 | Unmute the given ALSA | |
| 180 | .B <control> | |
| 181 | at daemon startup and set it to full volume. Use software volume adjustment for | |
| 182 | playback. This option is mutually exclusive with the \fB\-V\fR option. Only | |
| 183 | applicable when using ALSA output. | |
| 184 | .TP | |
| 185 | .B \-V <control> | |
| 186 | Use the given ALSA | |
| 187 | .B <control> | |
| 188 | for volume adjustment during playback. This prevents the use of software volume | |
| 189 | control within \fBsqueezelite\fR. This option is mutually exclusive with the | |
| 190 | \fB\-V\fR option. If neither \fB\-U\fR nor \fB\-V\fR options are provided, | |
| 191 | no ALSA controls are adjusted while running \fBsqueezelite\fR and software | |
| 192 | volume control is used instead. Only applicable when using ALSA output. | |
| 193 | .TP | |
| 194 | .B \-z | |
| 195 | Cause \fBsqueezelite\fR to run as a daemon. That is, it detaches itself from the | |
| 196 | terminal and runs in the background. | |
| 197 | .TP | |
| 198 | .B \-t | |
| 199 | Display version and license information. | |
| 200 | .SH RESAMPLING | |
| 201 | Audio can be resampled or upsampled before being sent to the output device. This | |
| 202 | can be enabled simply by passing the \fB\-u\fR option to \fBsqueezelite\fR, but | |
| 203 | further configuration can be given as an argument to the option. | |
| 204 | .PP | |
| 205 | Resampling is performed using the SoX Resampler library; the documentation for | |
| 206 | that library and the SoX \fIrate\fR effect many be helpful when configuring | |
| 207 | upsampling for \fBsqueezelite\fR. | |
| 208 | .PP | |
| 209 | The format of the argument is | |
| 210 | .B <recipe>:<flags>:<attenuation>:<precision>:<passband_end>:<stopband_start>:<phase_response> | |
| 211 | .SS recipe | |
| 212 | This part of the argument string is made up of a number of single-character | |
| 213 | flags: \fB[v|h|m|l|q][L|I|M][s][E|X]\fR. The default value is \fBhL\fR. | |
| 214 | .TP | |
| 215 | .IR v ", " h ", " m ", " l " or " q | |
| 216 | are mutually exclusive and correspond to very high, high, medium, low or quick | |
| 217 | quality. | |
| 218 | .TP | |
| 219 | .IR L ", " I " or " M | |
| 220 | correspond to linear, intermediate or minimum phase. | |
| 221 | .TP | |
| 222 | .IR s | |
| 223 | changes resampling bandwidth from the default 95% (based on the 3dB point) to | |
| 224 | 99%. | |
| 225 | .TP | |
| 226 | .IR E | |
| 227 | exception - avoids resampling if the output device supports the playback sample | |
| 228 | rate natively. | |
| 229 | .TP | |
| 230 | .IR X | |
| 231 | resamples to the maximum sample rate for the output device ("asynchronous" | |
| 232 | resampling). | |
| 233 | .TP | |
| 234 | .B Examples | |
| 235 | .B \-u vLs | |
| 236 | would use very high quality setting, linear phase filter and steep cut-off. | |
| 237 | .br | |
| 238 | .B \-u hM | |
| 239 | would specify high quality, with the minimum phase filter. | |
| 240 | .br | |
| 241 | .B \-u hMX | |
| 242 | would specify high quality, with the minimum phase filter and async upsampling | |
| 243 | to max device rate. | |
| 244 | .SS flags | |
| 245 | The second optional argument to \fB\-u\fR allows the user to specify the | |
| 246 | following arguments (taken from the \fIsoxr.h\fR header file), in hex: | |
| 247 | .sp | |
| 248 | #define SOXR_ROLLOFF_SMALL 0u /* <= 0.01 dB */ | |
| 249 | .br | |
| 250 | #define SOXR_ROLLOFF_MEDIUM 1u /* <= 0.35 dB */ | |
| 251 | .br | |
| 252 | #define SOXR_ROLLOFF_NONE 2u /* For Chebyshev bandwidth. */ | |
| 253 | .sp | |
| 254 | #define SOXR_MAINTAIN_3DB_PT 4u /* Reserved for internal use. */ | |
| 255 | .br | |
| 256 | #define SOXR_HI_PREC_CLOCK 8u /* Increase 'irrational' ratio accuracy. */ | |
| 257 | .br | |
| 258 | #define SOXR_DOUBLE_PRECISION 16u /* Use D.P. calcs even if precision <= 20. */ | |
| 259 | .br | |
| 260 | #define SOXR_VR 32u /* Experimental, variable-rate resampling. */ | |
| 261 | .TP | |
| 262 | .B Examples | |
| 263 | .B \-u :2 | |
| 264 | would specify \fBSOXR_ROLLOFF_NONE\fR. | |
| 265 | .sp | |
| 266 | \fBNB:\fR In the example above the first option, \fB<quality>\fR, has not been | |
| 267 | specified so would default to \fBhL\fR. Therefore, specifying \fB\-u :2\fR is | |
| 268 | equivalent to having specified \fB\-u hL:2\fR. | |
| 269 | .SS attenuation | |
| 270 | Internally, data is passed to the SoX resample process as 32 bit integers and | |
| 271 | output from the SoX resample process as 32 bit integers. Why does this matter? | |
| 272 | There is the possibility that integer samples, once resampled may be clipped | |
| 273 | (i.e. exceed the maximum value). By default, if you do not specify an | |
| 274 | \fBattenuation\fR value, it will default to \-1db. A value of \fI0\fR on the | |
| 275 | command line, i.e. \fB-u ::0\fR will disable the default \-1db attenuation being | |
| 276 | applied. | |
| 277 | .sp | |
| 278 | \fBNB:\fR Clipped samples will be logged. Keep an eye on the log file. | |
| 279 | .TP | |
| 280 | .B Examples | |
| 281 | .B \-u ::6 | |
| 282 | specifies to apply \-6db (ie. halve the volume) prior to the resampling process. | |
| 283 | .SS precision | |
| 284 | The internal 'bit' precision used in the re-sampling calculations (ie. quality). | |
| 285 | .sp | |
| 286 | \fBNB:\fR HQ = 20, VHQ = 28. | |
| 287 | .TP | |
| 288 | .B Examples | |
| 289 | .B \-u :::28 | |
| 290 | specifies 28-bit precision. | |
| 291 | .SS passband_end | |
| 292 | A percentage value between 0 and 100, where 100 is the Nyquist frequency. The | |
| 293 | default if not explicitly set is \fI91.3\fR. | |
| 294 | .TP | |
| 295 | .B Examples | |
| 296 | .B \-u ::::98 | |
| 297 | specifies passband ends at 98 percent of the Nyquist frequency. | |
| 298 | .SS stopband_start | |
| 299 | A percentage value between 0 and 100, where 100 is the Nyquist frequency. The | |
| 300 | default if not explicitly set is \fI100\fR. | |
| 301 | .TP | |
| 302 | .B Examples | |
| 303 | .B \-u :::::100 | |
| 304 | specifies that the stopband starts at the Nyquist frequency. | |
| 305 | .SS phase_response | |
| 306 | A value between 0-100, where \fI0\fR is equivalent to the recipe \fIM\fR flag | |
| 307 | for minimum phase, \fI25\fR is equivalent to the recipe \fII\fR flag for | |
| 308 | intermediate phase and \fI50\fR is equivalent to the recipe \fIL\fR flag for | |
| 309 | linear phase. | |
| 310 | .TP | |
| 311 | .B Examples | |
| 312 | .B \-u ::::::50 | |
| 313 | specifies linear phase. | |
| 314 | .SH SEE ALSO | |
| 315 | https://code.google.com/p/squeezelite/ | |
| 316 | .br | |
| 317 | .BR sox (1) | |
| 318 | \- for further information about resampling |