Annotation of src/usr.bin/sndioctl/sndioctl.1, Revision 1.1
1.1 ! ratchov 1: .\" $OpenBSD$
! 2: .\"
! 3: .\" Copyright (c) 2014-2020 Alexandre Ratchov <alex@caoua.org>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
! 8: .\"
! 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 16: .\"
! 17: .Dd $Mdocdate: April 8 2011 $
! 18: .Dt SNDIOCTL 1
! 19: .Os
! 20: .Sh NAME
! 21: .Nm sndioctl
! 22: .Nd control audio parameters
! 23: .Sh SYNOPSIS
! 24: .Nm
! 25: .Bk -words
! 26: .Op Fl iv
! 27: .Op Fl f Ar device
! 28: .Op Ar command ...
! 29: .Ek
! 30: .Nm
! 31: .Fl d
! 32: .Sh DESCRIPTION
! 33: The
! 34: .Nm
! 35: utility can display or change parameters of
! 36: .Xr sndio 7
! 37: audio devices.
! 38: The options are as follows:
! 39: .Bl -tag -width Ds
! 40: .It Fl d
! 41: Dump the raw list of available parameters and exit.
! 42: Useful as a debugging tool.
! 43: .It Fl f Ar device
! 44: Use this
! 45: .Xr sndio 7
! 46: audio device.
! 47: .It Fl i
! 48: Display characteristics of requested parameters
! 49: instead of their values.
! 50: .It Fl m
! 51: Monitor and display audio parameter changes.
! 52: .It Fl v
! 53: Enable verbose mode, a.k.a. multi-channel mode.
! 54: By default parameters affecting different channels
! 55: of the same stream are disguised as a single mono
! 56: parameter to hide details that are not essential.
! 57: .El
! 58: .Pp
! 59: If no commands are specified all valid parameters are displayed on
! 60: .Em stdout .
! 61: Unless
! 62: .Fl d ,
! 63: .Fl m ,
! 64: or
! 65: .Fl i
! 66: are used, displayed parameters are valid commands.
! 67: The set of available controls depends on the control device.
! 68: .Pp
! 69: Commands use the following two formats to display and set
! 70: parameters respectively:
! 71: .Pp
! 72: .Dl group/stream[channel].function
! 73: .Dl group/stream[channel].function=value
! 74: .Pp
! 75: On the left-hand side are specified the optional parameter group,
! 76: the affected stream name, and the optional channel number.
! 77: Examples of left-hand side terms:
! 78: .Pp
! 79: .Dl output.level
! 80: .Dl hw/spkr[6].mute
! 81: .Pp
! 82: There are 4 parameter types: switches, numbers, selectors, and vectors.
! 83: .Pp
! 84: Numbers are specified in decimal and follow the same semantics
! 85: as MIDI controllers.
! 86: Values are in the 0..127 range and 64 is the neutral state (if applicable).
! 87: Two-state controls (switches) take either 0 or 1 as value,
! 88: typically corresponding to the
! 89: .Em off
! 90: and
! 91: .Em on
! 92: states respectively.
! 93: .Pp
! 94: If a decimal is prefixed by the plus (minus) sign then
! 95: the given value is added to (subtracted from) the
! 96: current value of the control.
! 97: If
! 98: .Qq \&!
! 99: is used instead of a number, then the switch is toggled.
! 100: Examples:
! 101: .Pp
! 102: .Dl hw/spkr.level=85
! 103: .Dl hw/spkr.level=+10
! 104: .Dl hw/spkr.mute=0
! 105: .Dl hw/spkr.mute=!
! 106: .Pp
! 107: Selector values are substreams; they are specified
! 108: as the stream name followed by an optional channel
! 109: number.
! 110: If no channel number is specified, the same
! 111: number as the stream specified on the left-hand side is used.
! 112: For instance the following are equivalent:
! 113: .Pp
! 114: .Dl hw/record[1].source=mic
! 115: .Dl hw/record[1].source=mic1
! 116: .Pp
! 117: Vectors are arrays of numbers.
! 118: Values are specified as comma-separated components.
! 119: Each component is a substream, followed by
! 120: a colon, followed by a number.
! 121: If the colon and the number are omitted, then 127 is
! 122: assumed.
! 123: If a component is missing, then 0 is assumed.
! 124: Example:
! 125: .Pp
! 126: .Dl hw/monitor.mix=play:120,linein:85
! 127: .Dl hw/record.source=mic,linein
! 128: .Pp
! 129: Numbers are specified as discussed above.
! 130: Note that a vector of switches is equivalent to
! 131: a list.
! 132: .Sh EXAMPLES
! 133: The following will set all
! 134: .Ar level
! 135: parameters that control the
! 136: .Ar spkr
! 137: stream to zero.
! 138: .Pp
! 139: .Dl $ sndioctl hw/spkr.level=0
! 140: .Pp
! 141: The following commands are equivalent:
! 142: .Pp
! 143: .Dl $ sndioctl hw/record[0].source=mic0 hw/record[1].source=mic1
! 144: .Dl $ sndioctl hw/record.source=mic
! 145: .Sh SEE ALSO
! 146: .Xr sioctl_open 3