diff --git a/alsaaudio.pyi b/alsaaudio.pyi new file mode 100644 index 0000000..8e92d31 --- /dev/null +++ b/alsaaudio.pyi @@ -0,0 +1,135 @@ +from typing import list + +PCM_PLAYBACK: int +PCM_CAPTURE: int + +PCM_NORMAL: int +PCM_NONBLOCK: int +PCM_ASYNC: int + +PCM_FORMAT_S8: int +PCM_FORMAT_U8: int +PCM_FORMAT_S16_LE: int +PCM_FORMAT_S16_BE: int +PCM_FORMAT_U16_LE: int +PCM_FORMAT_U16_BE: int +PCM_FORMAT_S24_LE: int +PCM_FORMAT_S24_BE: int +PCM_FORMAT_U24_LE: int +PCM_FORMAT_U24_BE: int +PCM_FORMAT_S32_LE: int +PCM_FORMAT_S32_BE: int +PCM_FORMAT_U32_LE: int +PCM_FORMAT_U32_BE: int +PCM_FORMAT_FLOAT_LE: int +PCM_FORMAT_FLOAT_BE: int +PCM_FORMAT_FLOAT64_LE: int +PCM_FORMAT_FLOAT64_BE: int +PCM_FORMAT_MU_LAW: int +PCM_FORMAT_A_LAW: int +PCM_FORMAT_IMA_ADPCM: int +PCM_FORMAT_MPEG: int +PCM_FORMAT_GSM: int +PCM_FORMAT_S24_3LE: int +PCM_FORMAT_S24_3BE: int +PCM_FORMAT_U24_3LE: int +PCM_FORMAT_U24_3BE: int + +PCM_TSTAMP_NONE: int +PCM_TSTAMP_ENABLE: int + +PCM_TSTAMP_TYPE_GETTIMEOFDAY: int +PCM_TSTAMP_TYPE_MONOTONIC: int +PCM_TSTAMP_TYPE_MONOTONIC_RAW: int + +PCM_FORMAT_DSD_U8: int +PCM_FORMAT_DSD_U16_LE: int +PCM_FORMAT_DSD_U32_LE: int +PCM_FORMAT_DSD_U32_BE: int + +PCM_STATE_OPEN: int +PCM_STATE_SETUP: int +PCM_STATE_PREPARED: int +PCM_STATE_RUNNING: int +PCM_STATE_XRUN: int +PCM_STATE_DRAINING: int +PCM_STATE_PAUSED: int +PCM_STATE_SUSPENDED: int +PCM_STATE_DISCONNECTED: int + +MIXER_CHANNEL_ALL: int + +MIXER_SCHN_UNKNOWN: int +MIXER_SCHN_FRONT_LEFT: int +MIXER_SCHN_FRONT_RIGHT: int +MIXER_SCHN_REAR_LEFT: int +MIXER_SCHN_REAR_RIGHT: int +MIXER_SCHN_FRONT_CENTER: int +MIXER_SCHN_WOOFER: int +MIXER_SCHN_SIDE_LEFT: int +MIXER_SCHN_SIDE_RIGHT: int +MIXER_SCHN_REAR_CENTER: int +MIXER_SCHN_MONO: int + +VOLUME_UNITS_PERCENTAGE: int +VOLUME_UNITS_RAW: int +VOLUME_UNITS_DB: int + +def pcms(pcmtype: int) -> list[str]: ... +def cards() -> list[str]: ... +def mixers(cardindex: int = -1, device: str = 'default') -> list[str]: ... +def asoundlib_version() -> str: ... + +class PCM: + def __init__(type: int = PCM_PLAYBACK, mode: int = PCM_NORMAL, rate: int = 44100, channels: int = 2, + format: int = PCM_FORMAT_S16_LE, periodsize: int = 32, periods: int = 4, + device: str = 'default', cardindex: int = -1) -> PCM: ... + def close() -> None: ... + def dumpinfo() -> None: ... + def info() -> dict: ... + def state() -> int: ... + def htimestamp() -> tuple[int, int, int]: ... + def set_tstamp_mode(mode: int = PCM_TSTAMP_ENABLE) -> None: ... + def get_tstamp_mode() -> int: ... + def set_tstamp_type(type: int = PCM_TSTAMP_TYPE_GETTIMEOFDAY) -> None: ... + def get_tstamp_type() -> int: ... + def getformats() -> dict: ... + def getratebounds() -> tuple[int, int]: ... + def getrates() -> int | tuple[int, int] | list[int]: ... + def getchannels() -> list[int]: ... + def setchannels(nchannels: int) -> None: ... + def pcmtype() -> int: ... + def pcmmode() -> int: ... + def cardname() -> str: ... + def setrate(rate: int) -> None: ... + def setformat(format: int) -> int: ... + def setperiodsize(period: int) -> int: ... + def read() -> tuple[int, bytes]: ... + def write(data: bytes) -> int: ... + def avail() -> int: ... + def pause(enable: bool = True) -> int: ... + def drop() -> int: ... + def drain() -> int: ... + def polldescriptors() -> list[tuple[int, int]]: ... + def polldescriptors_revents(descriptors: list[tuple[int, int]]) -> int: ... + +class Mixer: + def __init__(control: str = 'Master', id: int = 0, cardindex: int = -1, device: str = 'default') -> Mixer: ... + def cardname() -> str: ... + def close() -> None: ... + def mixer() -> str: ... + def mixerid() -> int: ... + def switchcap() -> int: ... + def volumecap() -> int: ... + def getvolume(pcmtype: int = PCM_PLAYBACK, units: int = VOLUME_UNITS_PERCENTAGE) -> int: ... + def getrange(pcmtype: int = PCM_PLAYBACK, units: int = VOLUME_UNITS_RAW) -> tuple[int, int]: ... + def getenum() -> tuple[str, list[str]]: ... + def getmute() -> list[int]: ... + def getrec() -> list[int]: ... + def setvolume(volume: int, pcmtype: int = PCM_PLAYBACK, units: int = VOLUME_UNITS_PERCENTAGE, channel: (int | None) = None) -> None: ... + def setenum(index: int) -> None: ... + def setmute(mute: bool, channel: (int | None) = None) -> None: ... + def setrec(capture: int, channel: (int | None) = None) -> None: ... + def polldescriptors() -> list[tuple[int, int]]: ... + def handleevents() -> int: ... + diff --git a/doc/libalsaaudio.rst b/doc/libalsaaudio.rst index de78c1b..e7dacb9 100644 --- a/doc/libalsaaudio.rst +++ b/doc/libalsaaudio.rst @@ -10,7 +10,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA. -.. function:: pcms(pcmtype=PCM_PLAYBACK) +.. function:: pcms(pcmtype: int = PCM_PLAYBACK) ->list[str] List available PCM devices by name. @@ -34,7 +34,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA. *New in 0.8* -.. function:: cards() +.. function:: cards() -> list[str] List the available ALSA cards by name. This function is only moderately useful. If you want to see a list of available PCM devices, use :func:`pcms` @@ -46,7 +46,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA. .. function:: card_indexes() .. function:: card_name() -.. function:: mixers(cardindex=-1, device='default') +.. function:: mixers(cardindex: int = -1, device: str = 'default') -> list[str] List the available mixers. The arguments are: @@ -82,7 +82,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA. changed. Since 0.8, this functions returns the mixers for the default device, not the mixers for the first card. -.. function:: asoundlib_version() +.. function:: asoundlib_version() -> str Return a Python string containing the ALSA version found. @@ -96,7 +96,9 @@ PCM objects in :mod:`alsaaudio` can play or capture (record) PCM sound through speakers or a microphone. The PCM constructor takes the following arguments: -.. class:: PCM(type=PCM_PLAYBACK, mode=PCM_NORMAL, rate=44100, channels=2, format=PCM_FORMAT_S16_LE, periodsize=32, periods=4, device='default', cardindex=-1) +.. class:: PCM(type: int = PCM_PLAYBACK, mode: int = PCM_NORMAL, rate: int = 44100, channels: int = 2, + format: int = PCM_FORMAT_S16_LE, periodsize: int = 32, periods: int = 4, + device: str = 'default', cardindex: int = -1) -> PCM This class is used to represent a PCM device (either for playback or recording). The constructor's arguments are: @@ -187,7 +189,7 @@ following arguments: PCM objects have the following methods: -.. method:: PCM.info() +.. method:: PCM.info() -> dict Returns a dictionary containing the configuration of a PCM device. @@ -259,17 +261,17 @@ PCM objects have the following methods: Dumps the PCM object's configured parameters to stdout. -.. method:: PCM.pcmtype() +.. method:: PCM.pcmtype() -> int Returns the type of PCM object. Either :const:`PCM_CAPTURE` or :const:`PCM_PLAYBACK`. -.. method:: PCM.pcmmode() +.. method:: PCM.pcmmode() -> int Return the mode of the PCM object. One of :const:`PCM_NONBLOCK`, :const:`PCM_ASYNC`, or :const:`PCM_NORMAL` -.. method:: PCM.cardname() +.. method:: PCM.cardname() -> string Return the name of the sound card used by this PCM object. @@ -301,23 +303,23 @@ PCM objects have the following methods: Returns a dictionary of supported format codes (integers) keyed by their standard ALSA names (strings). -.. method:: PCM.setchannels(nchannels) +.. method:: PCM.setchannels(nchannels: int) -> int .. deprecated:: 0.9 Use the `channels` named argument to :func:`PCM`. -.. method:: PCM.setrate(rate) +.. method:: PCM.setrate(rate: int) -> int .. deprecated:: 0.9 Use the `rate` named argument to :func:`PCM`. -.. method:: PCM.setformat(format) +.. method:: PCM.setformat(format: int) -> int .. deprecated:: 0.9 Use the `format` named argument to :func:`PCM`. -.. method:: PCM.setperiodsize(period) +.. method:: PCM.setperiodsize(period: int) -> int .. deprecated:: 0.9 Use the `periodsize` named argument to :func:`PCM`. -.. method:: PCM.state() +.. method:: PCM.state() -> int Returs the current state of the stream, which can be one of :const:`PCM_STATE_OPEN` (this should not actually happen), @@ -332,7 +334,7 @@ PCM objects have the following methods: *New in 0.10* -.. method:: PCM.avail() +.. method:: PCM.avail() -> int For :const:`PCM_PLAYBACK` PCM objects, returns the number of writable (that is, free) frames in the buffer. @@ -346,7 +348,7 @@ PCM objects have the following methods: *New in 0.11* -.. method:: PCM.read() +.. method:: PCM.read() -> tuple[int, bytes] In :const:`PCM_NORMAL` mode, this function blocks until a full period is available, and then returns a tuple (length,data) where *length* is @@ -365,7 +367,7 @@ PCM objects have the following methods: To avoid the problem in the future, try using a larger period size and/or more periods, at the cost of higher latency. -.. method:: PCM.write(data) +.. method:: PCM.write(data: bytes) -> int Writes (plays) the sound in data. The length of data *must* be a multiple of the frame size, and *should* be exactly the size of a @@ -394,18 +396,18 @@ PCM objects have the following methods: in the kernel, and playout will continue afterwards. Make sure that the stream is drained before discarding the PCM handle. -.. method:: PCM.pause([enable=True]) +.. method:: PCM.pause([enable: int = True]) -> int If *enable* is :const:`True`, playback or capture is paused. Otherwise, playback/capture is resumed. -.. method:: PCM.drop() +.. method:: PCM.drop() -> int Stop the stream and drop residual buffered frames. *New in 0.9* -.. method:: PCM.drain() +.. method:: PCM.drain() -> int For :const:`PCM_PLAYBACK` PCM objects, play residual buffered frames and then stop the stream. In :const:`PCM_NORMAL` mode, @@ -415,14 +417,14 @@ PCM objects have the following methods: *New in 0.10* -.. method:: PCM.close() +.. method:: PCM.close() -> None Closes the PCM device. For :const:`PCM_PLAYBACK` PCM objects in :const:`PCM_NORMAL` mode, this function blocks until all pending playback is drained. -.. method:: PCM.polldescriptors() +.. method:: PCM.polldescriptors() -> list[tuple[int, int]] Returns a list of tuples of *(file descriptor, eventmask)* that can be used to wait for changes on the PCM with *select.poll*. @@ -430,7 +432,7 @@ PCM objects have the following methods: The *eventmask* value is compatible with `poll.register`__ in the Python :const:`select` module. -.. method:: PCM.polldescriptors_revents(descriptors) +.. method:: PCM.polldescriptors_revents(descriptors: list[tuple[int, int]]) -> int Processes the descriptor list returned by :func:`polldescriptors` after using it with *select.poll*, and returns a single *eventmask* value that @@ -439,29 +441,29 @@ PCM objects have the following methods: *New in 0.11* -.. method:: PCM.set_tstamp_mode([mode=PCM_TSTAMP_ENABLE]) +.. method:: PCM.set_tstamp_mode([mode: int = PCM_TSTAMP_ENABLE]) Set the ALSA timestamp mode on the device. The mode argument can be set to either :const:`PCM_TSTAMP_NONE` or :const:`PCM_TSTAMP_ENABLE`. -.. method:: PCM.get_tstamp_mode() +.. method:: PCM.get_tstamp_mode() -> int Return the integer value corresponding to the ALSA timestamp mode. The return value can be either :const:`PCM_TSTAMP_NONE` or :const:`PCM_TSTAMP_ENABLE`. -.. method:: PCM.set_tstamp_type([type=PCM_TSTAMP_TYPE_GETTIMEOFDAY]) +.. method:: PCM.set_tstamp_type([type: int = PCM_TSTAMP_TYPE_GETTIMEOFDAY]) -> None Set the ALSA timestamp mode on the device. The type argument can be set to either :const:`PCM_TSTAMP_TYPE_GETTIMEOFDAY`, :const:`PCM_TSTAMP_TYPE_MONOTONIC` or :const:`PCM_TSTAMP_TYPE_MONOTONIC_RAW`. -.. method:: PCM.get_tstamp_type() +.. method:: PCM.get_tstamp_type() -> int Return the integer value corresponding to the ALSA timestamp type. The return value can be either :const:`PCM_TSTAMP_TYPE_GETTIMEOFDAY`, :const:`PCM_TSTAMP_TYPE_MONOTONIC` or :const:`PCM_TSTAMP_TYPE_MONOTONIC_RAW`. -.. method:: PCM.htimestamp() +.. method:: PCM.htimestamp() -> tuple[int, int, int] Return a Python tuple *(seconds, nanoseconds, frames_available_in_buffer)*. @@ -523,7 +525,7 @@ Mixer Objects Mixer objects provides access to the ALSA mixer API. -.. class:: Mixer(control='Master', id=0, cardindex=-1, device='default') +.. class:: Mixer(control: str = 'Master', id: int = 0, cardindex: int = -1, device: str = 'default') -> Mixer Arguments are: @@ -550,20 +552,20 @@ Mixer objects provides access to the ALSA mixer API. Mixer objects have the following methods: -.. method:: Mixer.cardname() +.. method:: Mixer.cardname() -> str Return the name of the sound card used by this Mixer object -.. method:: Mixer.mixer() +.. method:: Mixer.mixer() -> str Return the name of the specific mixer controlled by this object, For example ``'Master'`` or ``'PCM'`` -.. method:: Mixer.mixerid() +.. method:: Mixer.mixerid() -> int Return the ID of the ALSA mixer controlled by this object. -.. method:: Mixer.switchcap() +.. method:: Mixer.switchcap() -> int Returns a list of the switches which are defined by this specific mixer. Possible values in this list are: @@ -583,7 +585,7 @@ Mixer objects have the following methods: To manipulate these switches use the :meth:`setrec` or :meth:`setmute` methods -.. method:: Mixer.volumecap() +.. method:: Mixer.volumecap() -> int Returns a list of the volume control capabilities of this mixer. Possible values in the list are: @@ -599,7 +601,7 @@ Mixer objects have the following methods: 'Joined Capture Volume' Manipulate sound capture volume for all channels at a time ======================== ================ -.. method:: Mixer.getenum() +.. method:: Mixer.getenum() -> tuple[str, list[str]] For enumerated controls, return the currently selected item and the list of items available. @@ -625,13 +627,13 @@ Mixer objects have the following methods: This method will return an empty tuple if the mixer is not an enumerated control. -.. method:: Mixer.setenum(index) +.. method:: Mixer.setenum(index: int) -> None For enumerated controls, sets the currently selected item. *index* is an index into the list of available enumerated items returned by :func:`getenum`. -.. method:: Mixer.getrange(pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_RAW) +.. method:: Mixer.getrange(pcmtype: int = PCM_PLAYBACK, units: int = VOLUME_UNITS_RAW) -> tuple[int, int] Return the volume range of the ALSA mixer controlled by this object. The value is a tuple of integers whose meaning is determined by the @@ -645,7 +647,7 @@ Mixer objects have the following methods: The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`, :const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`. -.. method:: Mixer.getvolume(pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_PERCENTAGE) +.. method:: Mixer.getvolume(pcmtype: int = PCM_PLAYBACK, units: int = VOLUME_UNITS_PERCENTAGE) -> int Returns a list with the current volume settings for each channel. The list elements are integers whose meaning is determined by the *units* argument. @@ -658,7 +660,7 @@ Mixer objects have the following methods: The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`, :const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`. -.. method:: Mixer.setvolume(volume, channel=None, pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_PERCENTAGE) +.. method:: Mixer.setvolume(volume: int, pcmtype: int = PCM_PLAYBACK, units: int = VOLUME_UNITS_PERCENTAGE, channel: (int | None) = None) -> None Change the current volume settings for this mixer. The *volume* argument is an integer whose meaning is determined by the *units* argument. @@ -675,14 +677,14 @@ Mixer objects have the following methods: The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`, :const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`. -.. method:: Mixer.getmute() +.. method:: Mixer.getmute() -> list[int] Return a list indicating the current mute setting for each channel. 0 means not muted, 1 means muted. This method will fail if the mixer has no playback switch capabilities. -.. method:: Mixer.setmute(mute, [channel]) +.. method:: Mixer.setmute(mute: bool, channel: (int | None) = None) -> None Sets the mute flag to a new value. The *mute* argument is either 0 for not muted, or 1 for muted. @@ -692,14 +694,14 @@ Mixer objects have the following methods: This method will fail if the mixer has no playback mute capabilities -.. method:: Mixer.getrec() +.. method:: Mixer.getrec() -> list[int] Return a list indicating the current record mute setting for each channel. 0 means not recording, 1 means recording. This method will fail if the mixer has no capture switch capabilities. -.. method:: Mixer.setrec(capture, [channel]) +.. method:: Mixer.setrec(capture: int, channel: (int | None) = None) -> None Sets the capture mute flag to a new value. The *capture* argument is either 0 for no capture, or 1 for capture. @@ -709,7 +711,7 @@ Mixer objects have the following methods: This method will fail if the mixer has no capture switch capabilities. -.. method:: Mixer.polldescriptors() +.. method:: Mixer.polldescriptors() -> list[tuple[int, int]] Returns a list of tuples of *(file descriptor, eventmask)* that can be used to wait for changes on the mixer with *select.poll*. @@ -717,13 +719,13 @@ Mixer objects have the following methods: The *eventmask* value is compatible with `poll.register`__ in the Python :const:`select` module. -.. method:: Mixer.handleevents() +.. method:: Mixer.handleevents() -> int Acknowledge events on the :func:`polldescriptors` file descriptors to prevent subsequent polls from returning the same events again. Returns the number of events that were acknowledged. -.. method:: Mixer.close() +.. method:: Mixer.close() -> None Closes the Mixer device.