o ٷi@sdZddlZddlZddlmZddlmZmZmZm Z m Z ddl Z ddl mZddlmZddlmZmZdd lmZdd lmZdd lmZdd lmZdd lmZddlmZgdZe jde jde jde jdiZ edZ!GdddZ"dS)zT Python wrapper around the SoX library. This module requires that SoX is installed. N)Path)ListOptionalDictUnionTuple)Literal) file_info) ENCODING_VALS EncodingValue)SoxError) VALID_FORMATS is_number)play)sox)logger)rr s16s8f32f64 amplitudepowerdbc@s eZdZdZddZ     dAdededed ed ef d d Zd dZddZ      dBde e de e de ede ede e def ddZddZddZ       dCde e de e de ede ede e de e d efd!d"Zd#d$Zd%d&Z      dBd'e ee efd(e ee efd)e e d*e e d+e ee d,ef d-d.Z      dBd'e ee efd(e ee efd)e ejd*e e d+e ee d,ef d/d0Z    dDd'e ee efd)e ejd*e e d+e ee fd1d2Zd'ee effd3d4ZdEd6e d7e fd8d9Z 5 dFd6e d7e d:efd;d<Z 5 dFd6e d7e d:efd=d>Z ? @dGdAe d6e dBe fdCdDZ E FdHdGedHee dIee dJee dKedLef dMdNZ!dOee dPee fdQdRZ"dSefdTdUZ# V W     dIdXe dYe dZed[e ee d\e ee d]e ee d^e ee d_e ee$d`fdadbZ%dcdddegdffdge dhe die djee&e e ffdkdlZ'dJdndoZ(   dKdpe e dSe edqe efdrdsZ)dLdue fdvdwZ*dxdyZ+dzee fd{d|Z,dMd}efd~dZ-ddZ.dddVddgdgfdXe dYe ded[ee d\ee f ddZ/dddVddgdgfdXe dYe ded[ee d\ee f ddZ0d6e d7e dAe fddZ1 t t dNde de de$dfddZ2dee fddZ3  @ E dOde de de de de de$dde de$dfddZ4 t   dPdAe dedede e$dfddZ5 dQd6e d7e defddZ6 dQd6e d7e defddZ7dRde efddZ8dSdAe de fddZ9ddgddgddgdedggdgdgddgfdedee dgee dhee diee e djeee&e e fdee e fddńZ:d'ee efdee effddȄZ;dTdee efde fdd˄Z<dUde fddτZ=ddфZ>dVdAe de fddՄZ?dWde de fddلZ@ @ ېdXdXe dYe dede de de$df ddZAdYde defddZB dZdpe de$dfddZC  d[de eDeeefde efddZEd\defddZF d]de de de de de de defddZGddZH d^de$dde de defddZI     d_de$d d ee ee fd e d e ee ee fd e e f ddZJd}e fddZK  d`d'ee efde e de efddZLd'ee effddZMd'ee effddZNdad}e de fddZOddZP  d`d}e d e e$d!defd"d#ZQ $ @dbdAe d6e dBe fd%d&ZRdcde de fd(d)ZSdRd*e d+e e fd,d-ZTdMd}efd.d/ZU  0 1 2 1 tddde$d3ded4e d5e d6e d7e d8e fd9d:ZV ; dede de e fd?d@ZWdS(f TransformeraAudio file transformer. Class which allows multiple effects to be chained to create an output file, saved to output_filepath. Methods ------- set_globals Overwrite the default global arguments. build Execute the current chain of commands to create an output file. build_file Alias of build. build_array Execute the current chain of commands to create an output array. cCs*i|_i|_g|_g|_g|_|dS)a Attributes ---------- input_format : list of str Input file format arguments that will be passed to SoX. output_format : list of str Output file format arguments that will be bassed to SoX. effects : list of str Effects arguments that will be passed to SoX. effects_log : list of str Ordered sequence of effects applied. globals : list of str Global arguments that will be passed to SoX. N) input_format output_formateffects effects_logglobals set_globalsselfr(A/home/ubuntu/.local/lib/python3.10/site-packages/sox/transform.py__init__9s  zTransformer.__init__Frditherguard multithread replay_gain verbositycCst|ts tdt|tstdt|tstdt|ts$td|tvr/tdtg}|s8|d|r?|d|rF|d|rR|d |d |d |||_|S) uSets SoX's global arguments. Overwrites any previously set global arguments. If this function is not explicity called, globals are set to this function's defaults. Parameters ---------- dither : bool, default=False If True, dithering is applied for low files with low bit rates. guard : bool, default=False If True, invokes the gain effect to guard against clipping. multithread : bool, default=False If True, each channel is processed in parallel. replay_gain : bool, default=False If True, applies replay-gain adjustment to input-files. verbosity : int, default=2 SoX's verbosity level. One of: * 0 : No messages are shown at all * 1 : Only error messages are shown. These are generated if SoX cannot complete the requested commands. * 2 : Warning messages are also shown. These are generated if SoX can complete the requested commands, but not exactly according to the requested command parameters, or if clipping occurs. * 3 : Descriptions of SoX’s processing phases are also shown. Useful for seeing exactly how SoX is processing your audio. * 4, >4 : Messages to help with debugging SoX are also shown. zdither must be a boolean.zguard must be a boolean.zmultithread must be a boolean.zreplay_gain must be a boolean.z+Invalid value for VERBOSITY. Must be one {}z-Dz-Gz--multi-threadedz --replay-gaintrackz-V) isinstancebool ValueErrorVERBOSITY_VALSformatappendr$)r'r+r,r-r.r/ global_argsr(r(r)r%Rs6 "        zTransformer.set_globalscCs"|d}|d}|d}|d}|d}|dd}|tdgvr-td tt|s9|dur9td |durE|d krEtd t|tsR|durRtd |dur^|d kr^tdt|tsk|durktd|durw|d krwtd|tdgvrtd|tt|tstddS)=Private helper function for validating input formats file_typeratebitschannelsencoding ignore_lengthFN"Invalid file_type. Must be one of rate must be a float or Nonerrate must be a positive numberbits must be an int or Nonebits must be a positive numberchannels must be an int or None"channels must be a positive numberz&Invalid encoding {}. Must be one of {}zignore_length must be a boolean) getrr3rr1intr r5r2)r'r r9r:r;r<r=r>r(r(r)_validate_input_formats>       z"Transformer._validate_input_formatc Cs|||d}|d}|d}|d}|d}|dd}g}|dur2|d |g|dur?|d |d g|durK|d |g|durW|d |g|durc|d|g|rj|d|S)z5Private helper function for set_input_format r9r:r;r<r=r>FN-t-rf-b-c-ez--ignore-length)rHrFextendr6) r'r r9r:r;r<r=r>input_format_argsr(r(r)_input_format_argss*        zTransformer._input_format_argsNr9r:r;r<r=r>cCs&||||||d}||||_dS)uSets input file format arguments. This is primarily useful when dealing with audio files without a file extension. Overwrites any previously set input file arguments. If this function is not explicity called the input format is inferred from the file extension or the file's header. Parameters ---------- file_type : str or None, default=None The file type of the input audio file. Should be the same as what the file extension would be, for ex. 'mp3' or 'wav'. rate : float or None, default=None The sample rate of the input audio file. If None the sample rate is inferred. bits : int or None, default=None The number of bits per sample. If None, the number of bits per sample is inferred. channels : int or None, default=None The number of channels in the audio file. If None the number of channels is inferred. encoding : str or None, default=None The audio encoding type. Sometimes needed with file-types that support more than one encoding type. One of: * signed-integer : PCM data stored as signed (‘two’s complement’) integers. Commonly used with a 16 or 24−bit encoding size. A value of 0 represents minimum signal power. * unsigned-integer : PCM data stored as unsigned integers. Commonly used with an 8-bit encoding size. A value of 0 represents maximum signal power. * floating-point : PCM data stored as IEEE 753 single precision (32-bit) or double precision (64-bit) floating-point (‘real’) numbers. A value of 0 represents minimum signal power. * a-law : International telephony standard for logarithmic encoding to 8 bits per sample. It has a precision equivalent to roughly 13-bit PCM and is sometimes encoded with reversed bit-ordering. * u-law : North American telephony standard for logarithmic encoding to 8 bits per sample. A.k.a. μ-law. It has a precision equivalent to roughly 14-bit PCM and is sometimes encoded with reversed bit-ordering. * oki-adpcm : OKI (a.k.a. VOX, Dialogic, or Intel) 4-bit ADPCM; it has a precision equivalent to roughly 12-bit PCM. ADPCM is a form of audio compression that has a good compromise between audio quality and encoding/decoding speed. * ima-adpcm : IMA (a.k.a. DVI) 4-bit ADPCM; it has a precision equivalent to roughly 13-bit PCM. * ms-adpcm : Microsoft 4-bit ADPCM; it has a precision equivalent to roughly 14-bit PCM. * gsm-full-rate : GSM is currently used for the vast majority of the world’s digital wireless telephone calls. It utilises several audio formats with different bit-rates and associated speech quality. SoX has support for GSM’s original 13kbps ‘Full Rate’ audio format. It is usually CPU-intensive to work with GSM audio. ignore_length : bool, default=False If True, overrides an (incorrect) audio length given in an audio file’s header. If this option is given then SoX will keep reading audio until it reaches the end of the input file. r9r:r;r<r=r>N)rHr )r'r9r:r;r<r=r>r r(r(r)set_input_formatsF  zTransformer.set_input_formatc CsD|d}|d}|d}|d}|d}|d}|dd}|td gvr2td tt|s>|d ur>td |d urJ|d krJtd t|tsW|d urWtd|d urc|d krctdt|tsp|d urptd|d ur||d kr|td|td gvrtdt|d urt|tstdt|tstdd S)r8r9r:r;r<r=commentsappend_commentsTNr?r@rrArBrCrDrEz!Invalid encoding. Must be one of z!comments must be a string or Nonez!append_comments must be a boolean) rFrr3rr1rGr strr2) r'r!r9r:r;r<r=rTrUr(r(r)_validate_output_format6s@        z#Transformer._validate_output_formatc Cs|||d}|d}|d}|d}|d}|d}|dd}g} |d ur7| d |g|d urD| d |d g|d urP| d |g|d ur\| d|g|d urh| d|g|d ur~|rw| d|g| S| d|g| S)z6Private helper function for set_output_format r9r:r;r<r=rTrUTNrIrJrKrLrMrNz --add-commentz --comment)rWrFrO) r'r!r9r:r;r<r=rTrUoutput_format_argsr(r(r)_output_format_argscs2        zTransformer._output_format_argsTrTrUc Cs(|||||||d}||||_dS)uSets output file format arguments. These arguments will overwrite any format related arguments supplied by other effects (e.g. rate). If this function is not explicity called the output format is inferred from the file extension or the file's header. Parameters ---------- file_type : str or None, default=None The file type of the output audio file. Should be the same as what the file extension would be, for ex. 'mp3' or 'wav'. rate : float or None, default=None The sample rate of the output audio file. If None the sample rate is inferred. bits : int or None, default=None The number of bits per sample. If None, the number of bits per sample is inferred. channels : int or None, default=None The number of channels in the audio file. If None the number of channels is inferred. encoding : str or None, default=None The audio encoding type. Sometimes needed with file-types that support more than one encoding type. One of: * signed-integer : PCM data stored as signed (‘two’s complement’) integers. Commonly used with a 16 or 24−bit encoding size. A value of 0 represents minimum signal power. * unsigned-integer : PCM data stored as unsigned integers. Commonly used with an 8-bit encoding size. A value of 0 represents maximum signal power. * floating-point : PCM data stored as IEEE 753 single precision (32-bit) or double precision (64-bit) floating-point (‘real’) numbers. A value of 0 represents minimum signal power. * a-law : International telephony standard for logarithmic encoding to 8 bits per sample. It has a precision equivalent to roughly 13-bit PCM and is sometimes encoded with reversed bit-ordering. * u-law : North American telephony standard for logarithmic encoding to 8 bits per sample. A.k.a. μ-law. It has a precision equivalent to roughly 14-bit PCM and is sometimes encoded with reversed bit-ordering. * oki-adpcm : OKI (a.k.a. VOX, Dialogic, or Intel) 4-bit ADPCM; it has a precision equivalent to roughly 12-bit PCM. ADPCM is a form of audio compression that has a good compromise between audio quality and encoding/decoding speed. * ima-adpcm : IMA (a.k.a. DVI) 4-bit ADPCM; it has a precision equivalent to roughly 13-bit PCM. * ms-adpcm : Microsoft 4-bit ADPCM; it has a precision equivalent to roughly 14-bit PCM. * gsm-full-rate : GSM is currently used for the vast majority of the world’s digital wireless telephone calls. It utilises several audio formats with different bit-rates and associated speech quality. SoX has support for GSM’s original 13kbps ‘Full Rate’ audio format. It is usually CPU-intensive to work with GSM audio. comments : str or None, default=None If not None, the string is added as a comment in the header of the output audio file. If None, no comments are added. append_comments : bool, default=True If True, comment strings are appended to SoX's default comments. If False, the supplied comment replaces the existing comment. r9r:r;r<r=rTrUN)rWr!) r'r9r:r;r<r=rTrUr!r(r(r)set_output_formatsH zTransformer.set_output_formatcCst|_t|_|S)z&Remove all effects processes. )listr"r#r&r(r(r) clear_effectsszTransformer.clear_effectscCs|dur |dur td|dur*t||j}|ddur&t||d<||fS|dur_t|tjs8t d|dur@tdd}t |j j |dt |jdkrU|jdnddd d }||fStd ) aMPrivate helper function for parsing inputs to build and build_array Parameters ---------- input_filepath : str or None Either path to input audio file or None. input_array : np.ndarray or None A np.ndarray of an waveform with shape (n_samples, n_channels) or None sample_rate_in : int or None Sample rate of input_array or None Returns ------- input_format : dict Input format dictionary input_filepath : str Formatted input filepath. Nz;Only one of input_filepath and input_array may be specifiedr<z)input_array must be a numpy array or Nonez1sample_rate_in must be specified for array inputs-r FrRz6One of input_filepath or input_array must be specified)r3r validate_input_filer rFr<r1npndarray TypeErrorENCODINGS_MAPPINGdtypetypelenshape)r'input_filepath input_arraysample_rate_inr r(r(r) _parse_inputss:   zTransformer._parse_inputsrioutput_filepathrjrk extra_args return_outputc Cs||||\}}|durtd||krtdt|g}||j||||||||j ||||j |durYt |t sTtd||t ||d\} } } | dkrptd| d| td |d |j|r| | | fSdS) a Given an input file or array, creates an output_file on disk by executing the current set of commands. This function returns True on success. If return_output is True, this function returns a triple of (status, out, err), giving the success state, along with stdout and stderr returned by sox. Parameters ---------- input_filepath : str or None Either path to input audio file or None for array input. output_filepath : str Path to desired output file. If a file already exists at the given path, the file will be overwritten. If '-n', no file is created. input_array : np.ndarray or None An np.ndarray of an waveform with shape (n_samples, n_channels). sample_rate_in must also be provided. If None, input_filepath must be specified. sample_rate_in : int Sample rate of input_array. This argument is ignored if input_array is None. extra_args : list or None, default=None If a list is given, these additional arguments are passed to SoX at the end of the list of effects. Don't use this argument unless you know exactly what you're doing! return_output : bool, default=False If True, returns the status and information sent to stderr and stdout as a tuple (status, stdout, stderr). If output_filepath is None, return_output=True by default. If False, returns True on success. Returns ------- status : bool True on success. out : str (optional) This is not returned unless return_output is True. When returned, captures the stdout produced by sox. err : str (optional) This is not returned unless return_output is True. When returned, captures the stderr produced by sox. Examples -------- >>> import numpy as np >>> import sox >>> tfm = sox.Transformer() >>> sample_rate = 44100 >>> y = np.sin(2 * np.pi * 440.0 * np.arange(sample_rate * 1.0) / sample_rate) file in, file out - basic usage >>> status = tfm.build('path/to/input.wav', 'path/to/output.mp3') file in, file out - equivalent usage >>> status = tfm.build( input_filepath='path/to/input.wav', output_filepath='path/to/output.mp3' ) array in, file out >>> status = tfm.build( input_array=y, sample_rate_in=sample_rate, output_filepath='path/to/output.mp3' ) Nz!output_filepath is not specified!z6input_filepath must be different from output_filepath.extra_args must be a list.TrStdout: Stderr: zCreated %s with effects: %s )rlr3r validate_output_filerOr$rQr6rYr!r"r1r\rr rinfojoinr#) r'rirmrjrkrnror argsstatusouterrr(r(r)buildsDL         zTransformer.buildcCs|||||||S)a An alias for build. Given an input file or array, creates an output_file on disk by executing the current set of commands. This function returns True on success. If return_output is True, this function returns a triple of (status, out, err), giving the success state, along with stdout and stderr returned by sox. Parameters ---------- input_filepath : str or None Either path to input audio file or None for array input. output_filepath : str Path to desired output file. If a file already exists at the given path, the file will be overwritten. If '-n', no file is created. input_array : np.ndarray or None An np.ndarray of an waveform with shape (n_samples, n_channels). sample_rate_in must also be provided. If None, input_filepath must be specified. sample_rate_in : int Sample rate of input_array. This argument is ignored if input_array is None. extra_args : list or None, default=None If a list is given, these additional arguments are passed to SoX at the end of the list of effects. Don't use this argument unless you know exactly what you're doing! return_output : bool, default=False If True, returns the status and information sent to stderr and stdout as a tuple (status, stdout, stderr). If output_filepath is None, return_output=True by default. If False, returns True on success. Returns ------- status : bool True on success. out : str (optional) This is not returned unless return_output is True. When returned, captures the stdout produced by sox. err : str (optional) This is not returned unless return_output is True. When returned, captures the stderr produced by sox. Examples -------- >>> import numpy as np >>> import sox >>> tfm = sox.Transformer() >>> sample_rate = 44100 >>> y = np.sin(2 * np.pi * 440.0 * np.arange(sample_rate * 1.0) / sample_rate) file in, file out - basic usage >>> status = tfm.build('path/to/input.wav', 'path/to/output.mp3') file in, file out - equivalent usage >>> status = tfm.build( input_filepath='path/to/input.wav', output_filepath='path/to/output.mp3' ) array in, file out >>> status = tfm.build( input_array=y, sample_rate_in=sample_rate, output_filepath='path/to/output.mp3' ) )r{)r'rirmrjrkrnror(r(r) build_filesMzTransformer.build_filecs<||||\}gd}t|t|j@rtdd}ddur(tj}n fddt Dd}t |j d }d ||d ddd d } |j ddurX|j d| d<|j d durg|j d | d <|j ddurx|j d}|| d<|d krtj }n|dkrtj}n|dkrtj}n|dkrtj}ntd|g} | |j| || || || | || |j|durt|tstd| |t| |d\} } } | dkrtd| d| tj| |d} | d dkr| j| d tt| | d fddj} t dd!|j| S)a\Given an input file or array, returns the ouput as a numpy array by executing the current set of commands. By default the array will have the same sample rate as the input file unless otherwise specified using set_output_format. Functions such as rate, channels and convert will be ignored! Parameters ---------- input_filepath : str or None Either path to input audio file or None. input_array : np.ndarray or None A np.ndarray of an waveform with shape (n_samples, n_channels). If this argument is passed, sample_rate_in must also be provided. If None, input_filepath must be specified. sample_rate_in : int Sample rate of input_array. This argument is ignored if input_array is None. extra_args : list or None, default=None If a list is given, these additional arguments are passed to SoX at the end of the list of effects. Don't use this argument unless you know exactly what you're doing! Returns ------- output_array : np.ndarray Output audio as a numpy array Examples -------- >>> import numpy as np >>> import sox >>> tfm = sox.Transformer() >>> sample_rate = 44100 >>> y = np.sin(2 * np.pi * 440.0 * np.arange(sample_rate * 1.0) / sample_rate) file in, array out >>> output_array = tfm.build(input_filepath='path/to/input.wav') array in, array out >>> output_array = tfm.build(input_array=y, sample_rate_in=sample_rate) specifying the output sample rate >>> tfm.set_output_format(rate=8000) >>> output_array = tfm.build(input_array=y, sample_rate_in=sample_rate) if an effect changes the number of channels, you must explicitly specify the number of output channels >>> tfm.remix(remix_dictionary={1: [1], 2: [1], 3: [1]}) >>> tfm.set_output_format(channels=3) >>> output_array = tfm.build(input_array=y, sample_rate_in=sample_rate) )r:r<convertzWhen outputting to an array, rate, channels and convert effects may be ignored. Use set_output_format() to specify output formats.r^r9Ncs g|] \}}d|kr|qS)r9r().0kvr r(r) 4s  z+Transformer.build_array..rrawr<TrZr:r; @zinvalid n_bits rpFrqrr)rer F)orderzCreated array with effects: %srs)"rlsetr#rwarningrFraint16rditemsreitemsizer!int8float32float64r3rOr$rQr6rYr"r1r\rr frombufferreshaperGrgTrurv)r'rirjrkrnignored_commandsrm encoding_outn_bitsr!rwrxryrzr(rr) build_arrays?          zTransformer.build_arraycCsBddg}||j||j||||jt|dS)zPlay a preview of the output with the current set of effects Parameters ---------- input_filepath : str Path to input audio file. rz--no-show-progressN)rOr$r r6r"r)r'rirwr(r(r)preview|s      zTransformer.preview@ frequencywidth_qcCsbt|r|dkr tdt|r|dkrtdd|d|ddg}|j||jd|S)u1Apply a two-pole all-pass filter. An all-pass filter changes the audio’s frequency to phase relationship without changing its frequency to amplitude relationship. The filter is described in detail in at http://musicdsp.org/files/Audio-EQ-Cookbook.txt Parameters ---------- frequency : float The filter's center frequency in Hz. width_q : float, default=2.0 The filter's width as a Q-factor. See Also -------- equalizer, highpass, lowpass, sinc r$frequency must be a positive number."width_q must be a positive number.allpassrKqrr3r"rOr#r6)r'rr effect_argsr(r(r)rs  zTransformer.allpassconstant_skirtcCt|r|dkr tdt|r|dkrtdt|ts!tddg}|r+|d||d|ddg|j||jd|S) aApply a two-pole Butterworth band-pass filter with the given central frequency, and (3dB-point) band-width. The filter rolls off at 6dB per octave (20dB per decade) and is described in detail in http://musicdsp.org/files/Audio-EQ-Cookbook.txt Parameters ---------- frequency : float The filter's center frequency in Hz. width_q : float, default=2.0 The filter's width as a Q-factor. constant_skirt : bool, default=False If True, selects constant skirt gain (peak gain = width_q). If False, selects constant 0dB peak gain. See Also -------- bandreject, sinc rrr!constant_skirt must be a boolean.bandpassrMrKrrr3r1r2r6rOr"r#r'rrrrr(r(r)r    zTransformer.bandpasscCr) aApply a two-pole Butterworth band-reject filter with the given central frequency, and (3dB-point) band-width. The filter rolls off at 6dB per octave (20dB per decade) and is described in detail in http://musicdsp.org/files/Audio-EQ-Cookbook.txt Parameters ---------- frequency : float The filter's center frequency in Hz. width_q : float, default=2.0 The filter's width as a Q-factor. constant_skirt : bool, default=False If True, selects constant skirt gain (peak gain = width_q). If False, selects constant 0dB peak gain. See Also -------- bandreject, sinc rrrr bandrejectrMrKrrrr(r(r)rrzTransformer.bandrejectY@?gain_dbslopecCt|stdt|r|dkrtdt|r |dks |dkr$tdd|d|d|ddg}|j||jd|S) u&Boost or cut the bass (lower) frequencies of the audio using a two-pole shelving filter with a response similar to that of a standard hi-fi’s tone-controls. This is also known as shelving equalisation. The filters are described in detail in http://musicdsp.org/files/Audio-EQ-Cookbook.txt Parameters ---------- gain_db : float The gain at 0 Hz. For a large cut use -20, for a large boost use 20. frequency : float, default=100.0 The filter's cutoff frequency in Hz. slope : float, default=0.5 The steepness of the filter's shelf transition. For a gentle slope use 0.3, and use 1.0 for a steep slope. See Also -------- treble, equalizer gain_db must be a numberrr?rbassrKsrr'rrrrr(r(r)rs   zTransformer.bassrn_bends start_times end_timescents frame_rateoversample_ratec Cst|tr |dkr tdt|trt||krtdtdd|Dr)tdt||kr3tdt|tr>t||krBtdtd d|DrOtd t||krYtd td dt||Dritd tddt|dd|ddDrtdt|trt||krtdtdd|Drtdt|tr|dks|dkrtdt|tr|dks|dkrtddd|d|g}d}t|D],} t || |d} t || || d} | | d d!|| d d!| d || }q|j ||j d|S)"aChanges pitch by specified amounts at specified times. The pitch-bending algorithm utilises the Discrete Fourier Transform (DFT) at a particular frame rate and over-sampling rate. Parameters ---------- n_bends : int The number of intervals to pitch shift start_times : list of floats A list of absolute start times (in seconds), in order end_times : list of floats A list of absolute end times (in seconds) in order. [start_time, end_time] intervals may not overlap! cents : list of floats A list of pitch shifts in cents. A positive value shifts the pitch up, a negative value shifts the pitch down. frame_rate : int, default=25 The number of DFT frames to process per second, between 10 and 80 oversample_rate: int, default=16 The number of frames to over sample per second, between 4 and 32 See Also -------- pitch r z#n_bends must be a positive integer.z-start_times must be a list of length n_bends.cSg|] }t| p |dkqSrrr~pr(r(r)rTz$Transformer.bend..z$start_times must be positive floats.z(start_times must be in increasing order.z+end_times must be a list of length n_bends.cSrrrrr(r(r)r]rz"end_times must be positive floats.z&end_times must be in increasing order.cSsg|]\}}||kqSr(r(r~rer(r(r)rcz8end_times must be element-wise greater than start_times.cSsg|]\}}||kqSr(r(rr(r(r)rhrNr_z9[start_time, end_time] intervals must be non-overlapping.z'cents must be a list of length n_bends.cSsg|]}t| qSr(rrr(r(r)rpz!elements of cents must be floats. Pz/frame_rate must be an integer between 10 and 80rrz4oversample_rate must be an integer between 4 and 32.bendz-fz-orrrK,)r1rGr3r\rganysortedziprangeroundr6r"rOr#) r'rrrrrrrlastit_startt_endr(r(r)r-sb!  (      zTransformer.bendbacCst|ts tdt|tstdt|dkrtdt|dkr&tdtdd|Ds3tdtd d|Ds@td d |d d |dd |dd |d d |dd |dd g}|j||jd |S)aQApply a biquad IIR filter with the given coefficients. Parameters ---------- b : list of floats Numerator coefficients. Must be length 3 a : list of floats Denominator coefficients. Must be length 3 See Also -------- fir, treble, bass, equalizer zb must be a list.za must be a list.rzb must be a length 3 list.za must be a length 3 list.cSg|]}t|qSr(r)r~b_valr(r(r)rz&Transformer.biquad..z"all elements of b must be numbers.cSrr(r)r~a_valr(r(r)rrz"all elements of a must be numbers.biquadrrKr r) r1r\r3rgallr"rOr#r6)r'rrrr(r(r)rs&      zTransformer.biquad n_channelscCs@t|tr |dkr tdd|g}|j||jd|S)aChange the number of channels in the audio signal. If decreasing the number of channels it mixes channels together, if increasing the number of channels it duplicates. Note: This overrides arguments used in the convert effect! Parameters ---------- n_channels : int Desired number of channels. See Also -------- convert r&n_channels must be a positive integer.r<r1rGr3r"rOr#r6)r'rrr(r(r)r<s    zTransformer.channels?rgain_ingain_outn_voicesdelaysdecaysspeedsdepthsshapes)rtc Cst|r |dks |dkrtdt|r|dks|dkr tdt|tr)|dkr-td|dus:t|ts:td|durVt||krHtdtd d |DrUtd n d d t|D}|duslt|tsltd|durt||krztdtdd |Drtdn dd t|D}|dust|tstd|durt||krtdtdd |Drtdn dd t|D}|dust|tstd|durt||krtdtdd |Drtdn dd t|D}|dust|tstd|dur#t||krtdtdd |Dr"td n d!d t|D}d"||g} t|D]"} | || d#|| d#|| d#|| d#d$|| gq7|j | |j d"|S)%a} Add a chorus effect to the audio. This can makeasingle vocal sound like a chorus, but can also be applied to instrumentation. Chorus resembles an echo effect with a short delay, but whereas with echo the delay is constant, with chorus, it is varied using sinusoidal or triangular modulation. The modulation depth defines the range the modulated delay is played before or after the delay. Hence the delayed sound will sound slower or faster, that is the delayed sound tuned around the original one, like in a chorus where some vocals are slightly off key. Parameters ---------- gain_in : float, default=0.3 The time in seconds over which the instantaneous level of the input signal is averaged to determine increases in volume. gain_out : float, default=0.8 The time in seconds over which the instantaneous level of the input signal is averaged to determine decreases in volume. n_voices : int, default=3 The number of voices in the chorus effect. delays : list of floats > 20 or None, default=None If a list, the list of delays (in miliseconds) of length n_voices. If None, the individual delay parameters are chosen automatically to be between 40 and 60 miliseconds. decays : list of floats or None, default=None If a list, the list of decays (as a fraction of gain_in) of length n_voices. If None, the individual decay parameters are chosen automatically to be between 0.3 and 0.4. speeds : list of floats or None, default=None If a list, the list of modulation speeds (in Hz) of length n_voices If None, the individual speed parameters are chosen automatically to be between 0.25 and 0.4 Hz. depths : list of floats or None, default=None If a list, the list of depths (in miliseconds) of length n_voices. If None, the individual delay parameters are chosen automatically to be between 1 and 3 miliseconds. shapes : list of 's' or 't' or None, default=None If a list, the list of modulation shapes - 's' for sinusoidal or 't' for triangular - of length n_voices. If None, the individual shapes are chosen automatically. rr )gain_in must be a number between 0 and 1.*gain_out must be a number between 0 and 1.z$n_voices must be a positive integer.Nzdelays must be a list or Nonez(the length of delays must equal n_voicescss"|] }t| p |dkVqdS)Nrrr(r(r)  z%Transformer.chorus..z+the elements of delays must be numbers > 20cSg|]}tddqS)(<randomuniformr~_r(r(r)rrz&Transformer.chorus..zdecays must be a list or Nonez(the length of decays must equal n_voicescs*|]}t| p|dkp|dkVqdSrr Nrrr(r(r)r!(.the elements of decays must be between 0 and 1cSr)333333?皙?rrr(r(r)r&rzspeeds must be a list or Nonez(the length of speeds must equal n_voicescs"|] }t| p |dkVqdSrNrrr(r(r)r.rz*the elements of speeds must be numbers > 0cSr)?rrrr(r(r)r1rzdepths must be a list or Nonez(the length of depths must equal n_voicescsrrrrr(r(r)r9rz*the elements of depths must be numbers > 0cSr)rg@rrr(r(r)r<rzshapes must be a list or Nonez(the length of shapes must equal n_voicescss|]}|dvVqdS)rrNr(rr(r(r)rDsz)the elements of shapes must be 's' or 't'cSsg|] }tddgqSr)rchoicerr(r(r)rGschorusrKr^ rr3r1rGr\rgrrrOr"r#r6) r'rrrrrrrrrrr(r(r)rs4             zTransformer.chorusr皙?@))r)iirr attack_time decay_time soft_knee_db tf_pointscCst|r|dkr tdt|r|dkrtd||kr!tdt|s-|dus-tdt|ts6tdt|dkr@tdtd d |DrMtd td d |DrZtd tdd |Drgtdtdd |Drttdt|tdd|Dkrtdt |ddd}g}|D]}| |dd|ddgqd|dd|dg}|dur| d |d |n| d ||j ||j d|S)aCompand (compress or expand) the dynamic range of the audio. Parameters ---------- attack_time : float, default=0.3 The time in seconds over which the instantaneous level of the input signal is averaged to determine increases in volume. decay_time : float, default=0.8 The time in seconds over which the instantaneous level of the input signal is averaged to determine decreases in volume. soft_knee_db : float or None, default=6.0 The ammount (in dB) for which the points at where adjacent line segments on the transfer function meet will be rounded. If None, no soft_knee is applied. tf_points : list of tuples Transfer function points as a list of tuples corresponding to points in (dB, dB) defining the compander's transfer function. See Also -------- mcompand, contrast rz&attack_time must be a positive number.z%decay_time must be a positive number.zattack_time is larger than decay_time. For most situations, attack_time should be shorter than decay time because the human ear is more sensitive to sudden loud music than sudden soft music.Nz&soft_knee_db must be a number or None.ztf_points must be a list.z'tf_points must have at least one point.cs|] }t|t VqdSNr1tupler~pairr(r(r)rz&Transformer.compand..z#elements of tf_points must be pairscs|] }t|dkVqdSrNrgr r(r(r)rrz$Tuples in tf_points must be length 2cs*|]}t|dot|d VqdSrrrr(r(r)rrz-Tuples in tf_points must be pairs of numbers.cs(|]}|ddkp|ddkVqdSrr(rr(r(r)r&z,Tuple values in tf_points must be <= 0 (dB).cSh|]}|dqSrr(rr(r(r) rz&Transformer.compand..z%Found duplicate x-value in tf_points.cS|dSNrr()rr(r(r)z%Transformer.compand..keyrKr compandr{:f}:{})rr3rrr1r\rcrgrrrOr6r5rvr"r#)r'rrrr transfer_listpointrr(r(r)rXsX    zTransformer.compandKcCHt|r |dks |dkrtdd|dg}|j||jd|S)aComparable with compression, this effect modifies an audio signal to make it sound louder. Parameters ---------- amount : float Amount of enhancement between 0 and 100. See Also -------- compand, mcompand rdz*amount must be a number between 0 and 100.contrastrKr)r'amountrr(r(r)r%s    zTransformer.contrast sampleratebitdepthcCsgd}|dur||vrtdt|d||jd<|dur1t|tr(|dkr,td||jd<|durFt|r=|dkrAtd |||S) aConverts output audio to the specified format. Parameters ---------- samplerate : float, default=None Desired samplerate. If None, defaults to the same as input. n_channels : int, default=None Desired number of channels. If None, defaults to the same as input. bitdepth : int, default=None Desired bitdepth. If None, defaults to the same as input. See Also -------- rate )rrrrNzbitdepth must be one of .r;rrr<z%samplerate must be a positive number.)r3rVr!r1rGrr:)r'r'rr( bitdepthsr(r(r)r}s$   zTransformer.convertshiftcCr#)zApply a DC shift to the audio. Parameters ---------- shift : float Amount to shift audio between -2 and 2. (Audio is between -1 and 1) See Also -------- highpass rz(shift must be a number between -2 and 2.dcshiftrKr)r'r-rr(r(r)r/s     zTransformer.dcshiftcC"dg}|j||jd|S)aApply Compact Disc (IEC 60908) de-emphasis (a treble attenuation shelving filter). Pre-emphasis was applied in the mastering of some CDs issued in the early 1980s. These included many classical music albums, as well as now sought-after issues of albums by The Beatles, Pink Floyd and others. Pre-emphasis should be removed at playback time by a de-emphasis filter in the playback device. However, not all modern CD players have this filter, and very few PC CD drives have it; playing pre-emphasised audio without the correct de-emphasis filter results in audio that sounds harsh and is far from what its creators intended. The de-emphasis filter is implemented as a biquad and requires the input audio sample rate to be either 44.1kHz or 48kHz. Maximum deviation from the ideal response is only 0.06dB (up to 20kHz). See Also -------- bass, treble deemphr"rOr#r6r'rr(r(r)r1s  zTransformer.deemph positionscCsbt|ts tdtdd|Dstddg}|dd|D|j||jd|S)aiDelay one or more audio channels such that they start at the given positions. Parameters ---------- positions: list of floats List of times (in seconds) to delay each audio channel. If fewer positions are given than the number of channels, the remaining channels will be unaffected. z%positions must be a a list of numberscss |] }t|o |dkVqdSrrrr(r(r)r*sz$Transformer.delay..z"positions must be positive nubmersdelaycSg|]}|dqSrKr(rr(r(r)r.rz%Transformer.delay..r1r\r3rrOr"r#r6)r'r4rr(r(r)r5s   zTransformer.delayfactorcC@t|tr |dkr tdd|g}|j||jd|S)a9Downsample the signal by an integer factor. Only the first out of each factor samples is retained, the others are discarded. No decimation filter is applied. If the input is not a properly bandlimited baseband signal, aliasing will occur. This may be desirable e.g., for frequency translation. For a general resampling effect with anti-aliasing, see rate. Parameters ---------- factor : int, default=2 Downsampling factor. See Also -------- rate, upsample r "factor must be a positive integer. downsamplerr'r9rr(r(r)r<4s    zTransformer.downsamplecCr0)umMakes audio easier to listen to on headphones. Adds ‘cues’ to 44.1kHz stereo audio so that when listened to on headphones the stereo image is moved from inside your head (standard for headphones) to outside and in front of the listener (standard for speakers). Warning: Will only work properly on 44.1kHz stereo audio! earwaxr2r3r(r(r)r>Qs  zTransformer.earwaxr rrn_echoscCs0t|r |dks |dkrtdt|r|dks|dkr tdt|tr)|dkr-tdt|ts6tdt||kr@tdtdd |DrMtd t|tsVtd t||kr`td td d |Drmtdd|d|dg}t|D]}|||||gqz|j ||j d|S)a Add echoing to the audio. Echoes are reflected sound and can occur naturally amongst mountains (and sometimes large buildings) when talking or shouting; digital echo effects emulate this behav- iour and are often used to help fill out the sound of a single instrument or vocal. The time differ- ence between the original signal and the reflection is the 'delay' (time), and the loudness of the reflected signal is the 'decay'. Multiple echoes can have different delays and decays. Parameters ---------- gain_in : float, default=0.8 Input volume, between 0 and 1 gain_out : float, default=0.9 Output volume, between 0 and 1 n_echos : int, default=1 Number of reflections delays : list, default=[60] List of delays in miliseconds decays : list, default=[0.4] List of decays, relative to gain in between 0 and 1 See Also -------- echos, reverb, chorus rr rr#n_echos must be a positive integer.zdelays must be a list'the length of delays must equal n_echoscsrrrrr(r(r)rrz#Transformer.echo..*the elements of delays must be numbers > 0zdecays must be a list'the length of decays must equal n_echoscsrrrrr(r(r)rrrechorKrr'rrr?rrrrr(r(r)rD`s:!       zTransformer.echocCs4t|r |dks |dkrtdt|r|dks|dkr tdt|tr)|dkr-tdt|ts6tdt||kr@tdtdd |DrMtd t|tsVtd t||kr`td td d |Drmtdd|d|dg}t|D]}|||d||dgqz|j ||j d|S)uAdd a sequence of echoes to the audio. Like the echo effect, echos stand for ‘ECHO in Sequel’, that is the first echos takes the input, the second the input and the first echos, the third the input and the first and the second echos, ... and so on. Care should be taken using many echos; a single echos has the same effect as a single echo. Parameters ---------- gain_in : float, default=0.8 Input volume, between 0 and 1 gain_out : float, default=0.9 Output volume, between 0 and 1 n_echos : int, default=1 Number of reflections delays : list, default=[60] List of delays in miliseconds decays : list, default=[0.4] List of decays, relative to gain in between 0 and 1 See Also -------- echo, reverb, chorus rr rrr@zthe delays must be a list rAcsrrrrr(r(r)rrz$Transformer.echos..rBzthe decays must be a list rCcsrrrrr(r(r)rrrechosrKrrEr(r(r)rFs<         zTransformer.echoscCsxt|r|dkr tdt|r|dkrtdt|s tdd|d|dd|dg}|j||jd|S)aApply a two-pole peaking equalisation (EQ) filter to boost or reduce around a given frequency. This effect can be applied multiple times to produce complex EQ curves. Parameters ---------- frequency : float The filter's central frequency in Hz. width_q : float The filter's width as a Q-factor. gain_db : float The filter's gain in dB. See Also -------- bass, treble rrrgain_db must be a number. equalizerrKrr)r'rrrrr(r(r)rHs   zTransformer.equalizerr fade_in_len fade_out_len fade_shaperhrlrcCsgd}||vrtdd|t|r|dkrtdt|r&|dkr*tdg}|dkr;|d||dg|dkrL|d d||dd gt|dkr^|j||jd|S) aAdd a fade in and/or fade out to an audio file. Default fade shape is 1/4 sine wave. Parameters ---------- fade_in_len : float, default=0.0 Length of fade-in (seconds). If fade_in_len = 0, no fade in is applied. fade_out_len : float, defaut=0.0 Length of fade-out (seconds). If fade_out_len = 0, no fade in is applied. fade_shape : str, default='q' Shape of fade. Must be one of * 'q' for quarter sine (default), * 'h' for half sine, * 't' for linear, * 'l' for logarithmic * 'p' for inverted parabola. See Also -------- splice rLzFade shape must be one of {}rsrz)fade_in_len must be a nonnegative number.z*fade_out_len must be a nonnegative number.faderKreverse) r3r5rvrrOrgr"r#r6)r'rIrJrK fade_shapesrr(r(r)rOs.    zTransformer.fade coefficientscCsbt|ts tdtdd|Dstddg}|dd|D|j||jd|S)uUse SoX’s FFT convolution engine with given FIR filter coefficients. Parameters ---------- coefficients : list fir filter coefficients zcoefficients must be a listcSrr(rr~cr(r(r)rcrz#Transformer.fir..zcoefficients must be numbers.fircSr6r7r(rSr(r(r)rgrr8)r'rRrr(r(r)rUWs   zTransformer.firrGsinelinearr5depthregenwidthspeedrhrWtrianglephaseinterprX quadraticc Cs.t|r |dks |dkrtdt|r|dks|dkr tdt|r,|dks,|dkr0tdt|r<|dks<|d kr@td t|rL|d ksL|dkrPtd |d vrXtdt|rd|dksd|d krhtd|dvrptdd|d|d|d|d|d||d|g } |j| |jd|S)aApply a flanging effect to the audio. Parameters ---------- delay : float, default=0 Base delay (in miliseconds) between 0 and 30. depth : float, default=2 Added swept delay (in miliseconds) between 0 and 10. regen : float, default=0 Percentage regeneration between -95 and 95. width : float, default=71, Percentage of delayed signal mixed with original between 0 and 100. speed : float, default=0.5 Sweeps per second (in Hz) between 0.1 and 10. shape : 'sine' or 'triangle', default='sine' Swept wave shape phase : float, default=25 Swept wave percentage phase-shift for multi-channel flange between 0 and 100. 0 = 100 = same phase on each channel interp : 'linear' or 'quadratic', default='linear' Digital delay-line interpolation type. See Also -------- tremolo rz(delay must be a number between 0 and 30.rz(depth must be a number between 0 and 10.i_z*regen must be a number between -95 and 95.r$z)width must be a number between 0 and 100.皙?z*speed must be a number between 0.1 and 10.r]z*shape must be one of 'sine' or 'triangle'.z)phase must be a number between 0 and 100.raz.interp must be one of 'linear' or 'quadratic'.flangerrKr) r'r5rYrZr[r\rhr_r`rr(r(r)rfns:  zTransformer.flanger normalizelimiterbalance)rBrcCst|stdt|tstdt|tstd|dvr"tddg}|dur1|d||r8|d |r?|d ||d |j||jd|S) a Apply amplification or attenuation to the audio signal. Parameters ---------- gain_db : float, default=0.0 Gain adjustment in decibels (dB). normalize : bool, default=True If True, audio is normalized to gain_db relative to full scale. If False, simply adjusts the audio power level by gain_db. limiter : bool, default=False If True, a simple limiter is invoked to prevent clipping. balance : str or None, default=None Balance gain across channels. Can be one of: * None applies no balancing (default) * 'e' applies gain to all channels other than that with the highest peak level, such that all channels attain the same peak level * 'B' applies gain to all channels other than that with the highest RMS level, such that all channels attain the same RMS level * 'b' applies gain with clipping protection to all channels other than that with the highest RMS level, such that all channels attain the same RMS level If normalize=True, 'B' and 'b' are equivalent. See Also -------- loudness rGznormalize must be a boolean.zlimiter must be a boolean.)Nrrjrz.balance must be one of None, 'e', 'B', or 'b'.gainNr^-n-lrK)rr3r1r2r6r"rOr#)r'rrgrhrirr(r(r)rks&#      zTransformer.gain9v?n_polescCt|r|dkr tdt|r|dkrtd|dvr tddd||dg}|d kr7||dd |j||jd|S) aApply a high-pass filter with 3dB point frequency. The filter can be either single-pole or double-pole. The filters roll off at 6dB per pole per octave (20dB per pole per decade). Parameters ---------- frequency : float The filter's cutoff frequency in Hz. width_q : float, default=0.707 The filter's width as a Q-factor. Applies only when n_poles=2. The default gives a Butterworth response. n_poles : int, default=2 The number of poles in the filter. Must be either 1 or 2 See Also -------- lowpass, equalizer, sinc, allpass rrrr rn_poles must be 1 or 2.highpassr^rKrrrr3r6r"rOr#r'rrrorr(r(r)rs  zTransformer.highpasscCrp) aApply a low-pass filter with 3dB point frequency. The filter can be either single-pole or double-pole. The filters roll off at 6dB per pole per octave (20dB per pole per decade). Parameters ---------- frequency : float The filter's cutoff frequency in Hz. width_q : float, default=0.707 The filter's width as a Q-factor. Applies only when n_poles=2. The default gives a Butterworth response. n_poles : int, default=2 The number of poles in the filter. Must be either 1 or 2 See Also -------- highpass, equalizer, sinc, allpass rrrrqrrlowpassr^rKrrrtrur(r(r)rwrvzTransformer.lowpassnum_tapscCsp|dur t|ts td|dur|ddkrtddg}|dur*|d|g|j||jd|S)akApply an odd-tap Hilbert transform filter, phase-shifting the signal by 90 degrees. This is used in many matrix coding schemes and for analytic signal generation. The process is often written as a multiplication by i (or j), the imaginary unit. An odd-tap Hilbert transform filter has a bandpass characteristic, attenuating the lowest and highest frequencies. Parameters ---------- num_taps : int or None, default=None Number of filter taps - must be odd. If none, it is chosen to have a cutoff frequency of about 75 Hz. Nz(num taps must be None or an odd integer.rrznum_taps must an odd integer.hilbertrl)r1rGr3rOr"r#r6)r'rxrr(r(r)ryHs  zTransformer.hilbert$@P@reference_levelcCsft|stdt|std|dks|dkrtdd|d|dg}|j||jd|S)aHLoudness control. Similar to the gain effect, but provides equalisation for the human auditory system. The gain is adjusted by gain_db and the signal is equalised according to ISO 226 w.r.t. reference_level. Parameters ---------- gain_db : float, default=-10.0 Loudness adjustment amount (in dB) reference_level : float, default=65.0 Reference level (in dB) according to which the signal is equalized. Must be between 50 and 75 (dB) See Also -------- gain rGz reference_level must be a numberr"2z)reference_level must be between 50 and 75loudnessrKr)r'rr|rr(r(r)r~gs  zTransformer.loudnessi@g{Gzt?g{GzD?reg?)iir)ir)rr)irrn_bandscrossover_frequenciesrkc CsJt|tr |dkr tdt|trt||dkrtdtdd|Dr+tdt|tr6t||kr:tdtdd|DrGtd t|trRt||krVtd td d|Drctd td dt||Drttdt|trt||krtdtdd|Drtdt|trt||krtdtdd|Drtd|D]G}tdd|Drtdtdd|Drtdtdd|Drtdtdd|Drtdt|tdd|Dkrtd qt|trt||krtd!td"d|Drtd#d$g} t |D]z} | d%kr.| || dd&|| d&d'|| d&g} || } t | d(d)d*} g} | D]}| |d%d&|dd&gqL|| d+uru| d, || d'| n| d'| || d+ur| || d&| d-| q|j | |j d$|S).a\ The multi-band compander is similar to the single-band compander but the audio is first divided into bands using Linkwitz-Riley cross-over filters and a separately specifiable compander run on each band. When used with n_bands=1, this effect is identical to compand. When using n_bands > 1, the first set of arguments applies a single band compander, and each subsequent set of arugments is applied on each of the crossover frequencies. Parameters ---------- n_bands : int, default=2 The number of bands. crossover_frequencies : list of float, default=[1600] A list of crossover frequencies in Hz of length n_bands-1. The first band is always the full spectrum, followed by the bands specified by crossover_frequencies. attack_time : list of float, default=[0.005, 0.000625] A list of length n_bands, where each element is the time in seconds over which the instantaneous level of the input signal is averaged to determine increases in volume over the current band. decay_time : list of float, default=[0.1, 0.0125] A list of length n_bands, where each element is the time in seconds over which the instantaneous level of the input signal is averaged to determine decreases in volume over the current band. soft_knee_db : list of float or None, default=[6.0, None] A list of length n_bands, where each element is the ammount (in dB) for which the points at where adjacent line segments on the transfer function meet will be rounded over the current band. If None, no soft_knee is applied. tf_points : list of list of tuples, default=[ [(-47, -40), (-34, -34), (-17, -33), (0, 0)], [(-47, -40), (-34, -34), (-15, -33), (0, 0)]] A list of length n_bands, where each element is the transfer function points as a list of tuples corresponding to points in (dB, dB) defining the compander's transfer function over the current band. gain : list of floats or None A list of gain values for each frequency band. If None, no gain is applied. See Also -------- compand, contrast r z#n_bands must be a positive integer.z9crossover_frequences must be a list of length n_bands - 1cSsg|] }t| p |dkqSrrr~rKr(r(r)rrz(Transformer.mcompand..z7crossover_frequencies elements must be positive floats.z,attack_time must be a list of length n_bandscSrrr)r~rr(r(r)rrz.attack_time elements must be positive numbers.z+decay_time must be a list of length n_bandscSrrrr~dr(r(r)rrz-decay_time elements must be positive numbers.cSsg|]\}}||kqSr(r()r~rrr(r(r)rrzElements of attack_time are larger than decay_time. For most situations, attack_time should be shorter than decay time because the human ear is more sensitive to sudden loud music than sudden soft music.z.soft_knee_db must be a list of length n_bands.cSsg|] }t| o |duqSr rrr(r(r)rrz2elements of soft_knee_db must be a number or None.z+tf_points must be a list of length n_bands.cSs$g|]}t|t pt|dkqSr)r1r\rg)r~rr(r(r)rs$z1tf_points must be a list with at least one point.csr r r r r(r(r)rrz'Transformer.mcompand..z)elements of tf_points lists must be pairscsrrrr r(r(r)rrz*Tuples in tf_points lists must be length 2csrrrrr(r(r)rrz3Tuples in tf_points lists must be pairs of numbers.csrrr(rr(r(r)r rz2Tuple values in tf_points lists must be <= 0 (dB).cSrrr(rr(r(r)r rz'Transformer.mcompand..z*Found duplicate x-value in tf_points list.z%gain must be a list of length n_bandscSsg|] }t|p |du qSr r)r~gr(r(r)r rz&gain elements must be numbers or None.mcompandrrKrcSrrr()tf_points_bandr(r(r)r rz&Transformer.mcompand..rNrrs)r1rGr3r\rgrrrrrr6rrOr5rvr"r#)r'rrrrrrrktfprr intermed_argsrr r!r(r(r)rs:      zTransformer.mcompand profile_pathcCstj|rtd|dtj|dkr$|dkr$tjt|}n|}ttj|tjs9t d|dd|g}|j |d|ddS) a Calculate a profile of the audio for use in noise reduction. Running this command does not effect the Transformer effects chain. When this function is called, the calculated noise profile file is saved to the `profile_path`. Parameters ---------- input_filepath : str Path to audiofile from which to compute a noise profile. profile_path : str Path to save the noise profile file. See Also -------- noisered profile_path z is a directory.z is not writeable. noiseprofrl)rnN) ospathisdirr3dirnamervgetcwdaccessW_OKOSErrorr{)r'rir_abs_profile_pathrr(r(r)r4 s   zTransformer.noiseprofr&cCsftj|std|dt|r|dks|dkrtdd||dg}|j||j d|S)aReduce noise in the audio signal by profiling and filtering. This effect is moderately effective at removing consistent background noise such as hiss or hum. Parameters ---------- profile_path : str Path to a noise profile file. This file can be generated using the `noiseprof` effect. amount : float, default=0.5 How much noise should be removed is specified by amount. Should be between 0 and 1. Higher numbers will remove more noise but present a greater likelihood of removing wanted components of the audio signal. See Also -------- noiseprof rz does not exist.rr z(amount must be a number between 0 and 1.noiseredrK) rrexistsrrr3r"rOr#r6)r'rr&rr(r(r)rZ s    zTransformer.noisereddb_levelcCs8t|stdd|dg}|j||jd|S)a+Normalize an audio file to a particular db level. This behaves identically to the gain effect with normalize=True. Parameters ---------- db_level : float, default=-3.0 Output volume (db) See Also -------- gain, loudness db_level must be a number.normrKr)r'rrr(r(r)r s  zTransformer.normcCr0)a6Out Of Phase Stereo effect. Mixes stereo to twin-mono where each mono channel contains the difference between the left and right stereo channels. This is sometimes known as the 'karaoke' effect as it often has the effect of removing most or all of the vocals from a recording. oopsr2r3r(r(r)r s  zTransformer.oops4@colourcCsNt|stdt|stdd|d|dg}|j||jd|S)aApply non-linear distortion. Parameters ---------- gain_db : float, default=20 Controls the amount of distortion (dB). colour : float, default=20 Controls the amount of even harmonic content in the output (dB). rzcolour must be a number. overdriverKr)r'rrrr(r(r)r s   zTransformer.overdrivestart_duration end_durationcCs^t|r|dkr tdt|r|dkrtdd|d|dg}|j||jd|S)aAdd silence to the beginning or end of a file. Calling this with the default arguments has no effect. Parameters ---------- start_duration : float Number of seconds of silence to add to beginning. end_duration : float Number of seconds of silence to add to end. See Also -------- delay rz)Start duration must be a positive number.zEnd duration must be positive.padrKr)r'rrrr(r(r)r s  zTransformer.padGz? sinusoidaldecaymodulation_shaper triangularcCst|r |dks |dkrtdt|r|dks|dkr tdt|r,|dks,|dkr0tdt|r<|dks<|dkr@td t|rL|dksL|d krPtd |d vrXtd d|d|d|d|d|dg}|dkrt|dn |dkr}|d|j||jd|S)aApply a phasing effect to the audio. Parameters ---------- gain_in : float, default=0.8 Input volume between 0 and 1 gain_out: float, default=0.74 Output volume between 0 and 1 delay : float, default=3 Delay in miliseconds between 0 and 5 decay : float, default=0.4 Decay relative to gain_in, between 0.1 and 0.5. speed : float, default=0.5 Modulation speed in Hz, between 0.1 and 2 modulation_shape : str, defaul='sinusoidal' Modulation shpae. One of 'sinusoidal' or 'triangular' See Also -------- flanger, tremolo rr rrz delay must be a positive number.rerz+decay must be a number between 0.1 and 0.5.r speed must be a positive number.rz;modulation_shape must be one of 'sinusoidal', 'triangular'.phaserrKr-srrIrt)r'rrr5rr\rrr(r(r)r s8    zTransformer.phaser n_semitonesquickcCs~t|std|dks|dkrtdt|tstddg}|r(|d||dd |j||j d|S) aPitch shift the audio without changing the tempo. This effect uses the WSOLA algorithm. The audio is chopped up into segments which are then shifted in the time domain and overlapped (cross-faded) at points where their waveforms are most similar as determined by measurement of least squares. Parameters ---------- n_semitones : float The number of semitones to shift. Can be positive or negative. quick : bool, default=False If True, this effect will run faster but with lower sound quality. See Also -------- bend, speed, tempo z%n_semitones must be a positive numberi z=Using an extreme pitch shift. Quality of results will be poorquick must be a boolean.pitch-qrrK) rr3rrr1r2r6r"rOr#)r'rrrr(r(r)r# s    zTransformer.pitchrMqualityrrNmrMrcCslgd}t|r |dkrtd||vrtdd|dd||dg}|j||jd|S) aChange the audio sampling rate (i.e. resample the audio) to any given `samplerate`. Better the resampling quality = slower runtime. Parameters ---------- samplerate : float Desired sample rate. quality : str Resampling quality. One of: * q : Quick - very low quality, * l : Low, * m : Medium, * h : High (default), * v : Very high See Also -------- upsample, downsample, convert rrz%Samplerate must be a positive number.zQuality must be one of {}.rsr:r^rK)rr3r5rvr"rOr#r6)r'r'r quality_valsrr(r(r)r:O s  zTransformer.rateremix_dictionarynum_output_channelscCs:t|ts |dus td|durCtdd|Ds tdtdd|Ds/td|D]}tdd|DsBtd q3t|trL|d ksT|dusTtd d g}|dura|d n.|durkt|}t d|dD]}||vrd dd||D}nd}||qr|j ||j d |S)aFRemix the channels of an audio file. Note: volume options are not yet implemented Parameters ---------- remix_dictionary : dict or None Dictionary mapping output channel to list of input channel(s). Empty lists indicate the corresponding output channel should be empty. If None, mixes all channels down to a single mono file. num_output_channels : int or None The number of channels in the output file. If None, the number of output channels is equal to the largest key in remix_dictionary. If remix_dictionary is None, this variable is ignored. Examples -------- Remix a 4-channel input file. The output file will have input channel 2 in channel 1, a mixdown of input channels 1 an 3 in channel 2, an empty channel 3, and a copy of input channel 4 in channel 4. >>> import sox >>> tfm = sox.Transformer() >>> remix_dictionary = {1: [2], 2: [1, 3], 4: [4]} >>> tfm.remix(remix_dictionary) Nz.remix_dictionary must be a dictionary or None.cSg|] }t|to |dkqSrr1rGr~rr(r(r)r rz%Transformer.remix..z1remix dictionary must have positive integer keys.cSsg|]}t|tqSr()r1r\r~rr(r(r)r rz&remix dictionary values must be lists.cSrrrrr(r(r)r rz=elements of remix dictionary values must be positive integersrz7num_output_channels must be a positive integer or None.remixr^r rcSrr()rVrr(r(r)r r0)r1dictr3rkeysvaluesrGr6maxrrvr"rOr#)r'rrv_listrchannel out_channelr(r(r)rx sP         zTransformer.remixcountcCs@t|tr |dkr tdd|g}|j||jddS)zRepeat the entire audio count times. Parameters ---------- count : int, default=1 The number of times to repeat the audio. r z count must be a postive integer.repeatNr)r'rrr(r(r)r s    zTransformer.repeatr}r$ reverberancehigh_freq_damping room_scale stereo_depth pre_delaywet_gainwet_onlyc Cst|r |dks |dkrtdt|r|dks|dkr tdt|r,|dks,|dkr0tdt|r<|dks<|dkr@tdt|rH|dkrLtdt|sTtdt|ts]td d g}|rg|d ||d |d |d |d |d |d g|j||jd |S) uAdd reverberation to the audio using the ‘freeverb’ algorithm. A reverberation effect is sometimes desirable for concert halls that are too small or contain so many people that the hall’s natural reverberance is diminished. Applying a small amount of stereo reverb to a (dry) mono signal will usually make it sound more natural. Parameters ---------- reverberance : float, default=50 Percentage of reverberance high_freq_damping : float, default=50 Percentage of high-frequency damping. room_scale : float, default=100 Scale of the room as a percentage. stereo_depth : float, default=100 Stereo depth as a percentage. pre_delay : float, default=0 Pre-delay in milliseconds. wet_gain : float, default=0 Amount of wet gain in dB wet_only : bool, default=False If True, only outputs the wet signal. See Also -------- echo rr$z&reverberance must be between 0 and 100z+high_freq_damping must be between 0 and 100z$room_scale must be between 0 and 100z&stereo_depth must be between 0 and 100z#pre_delay must be a positive numberzwet_gain must be a numberzwet_only must be a boolean.reverbz-wrKr) r'rrrrrrrrr(r(r)r s@%   zTransformer.reverbcCr0)z%Reverse the audio completely rPr2r3r(r(r)rP+ s  zTransformer.reverselocation)rr r_silence_thresholdmin_silence_durationbuffer_around_silencecCs|dvrtdt|r|dkrtd|dkrtdt|r$|dkr(tdt|ts1tdg}|dkr<|d |rF|d d gn|d |d |d |d dg|dkrk|d|d |d dg|dkrt|d |j||jd |S)acRemoves silent regions from an audio file. Parameters ---------- location : int, default=0 Where to remove silence. One of: * 0 to remove silence throughout the file (default), * 1 to remove silence from the beginning, * -1 to remove silence from the end, silence_threshold : float, default=0.1 Silence threshold as percentage of maximum sample amplitude. Must be between 0 and 100. min_silence_duration : float, default=0.1 The minimum ammount of time in seconds required for a region to be considered non-silent. buffer_around_silence : bool, default=False If True, leaves a buffer of min_silence_duration around removed silent regions. See Also -------- vad )r_rr z!location must be one of -1, 0, 1.rz4silence_threshold must be a number between 0 and 100r$z/min_silence_duration must be a positive number.z(buffer_around_silence must be a boolean.r_rPsilencerm1rK%z-1)r3rr1r2r6rOr"r#)r'rrrrrr(r(r)r4 sL        zTransformer.silencehigh x filter_typerlowpassreject cutoff_freqstop_band_attenuation transition_bwphase_responsecCsgd}||vrtdd|t|st|tstd|dvr,t|tr,td|dvr8t|r8tdt|rD|d krDtd t|trdt|d krStd td d|Dr`tdt|}t|rl|d krptdt|st|ts|dustd|dvrt|trtdt|r|d krtdt|trtdd|Drtdt|d krtd|durt|stdt|r|d ks|dkrtddg}| d|dg|dur| d|dg|dkr|dur| d |dg| |dn=|d!kr"| d"|d|dur!| d |dgn t|r1| d |dgnt|trB| d |d dg|d#krX| |d dd"|d$dn|d%krm| |d$dd"|d dt|tr~| d |d$dg|j ||j d|S)&a-Apply a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject filter to the signal. Parameters ---------- filter_type : str, default='high' Type of filter. One of: - 'high' for a high-pass filter - 'low' for a low-pass filter - 'pass' for a band-pass filter - 'reject' for a band-reject filter cutoff_freq : float or list, default=3000 A scalar or length 2 list indicating the filter's critical frequencies. The critical frequencies are given in Hz and must be positive. For a high-pass or low-pass filter, cutoff_freq must be a scalar. For a band-pass or band-reject filter, it must be a length 2 list. stop_band_attenuation : float, default=120 The stop band attenuation in dB transition_bw : float, list or None, default=None The transition band-width in Hz. If None, sox's default of 5% of the total bandwith is used. If a float, the given transition bandwith is used for both the upper and lower bands (if applicable). If a list, the first argument is used for the lower band and the second for the upper band. phase_response : float or None The filter's phase response between 0 (minimum) and 100 (maximum). If None, sox's default phase repsonse is used. See Also -------- band, bandpass, bandreject, highpass, lowpass rzfilter_type must be one of {}z, z&cutoff_freq must be a number or a list)rrzJFor filter types 'high' and 'low', cutoff_freq must be a float, not a list)rrzMFor filter types 'pass' and 'reject', cutoff_freq must be a list, not a floatrz$cutoff_freq must be a postive numberrz5If cutoff_freq is a list it may only have 2 elements.cSrrrrr(r(r)r rz$Transformer.sinc..z0elements of cutoff_freq must be positive numbersz/stop_band_attenuation must be a positive numberNz/transition_bw must be a number, a list or None.zLFor filter types 'high' and 'low', transition_bw must be a float, not a listz&transition_bw must be a postive numbercSrrrrr(r(r)r rz2elements of transition_bw must be positive numbersz7If transition_bw is a list it may only have 2 elements.z(phase_response must be a number or None.r$z(phase response must be between 0 and 100sincz-arK-prrIrr^rr r) r3r5rvrr1r\rgrrrOr6r"r#)r'rrrrr filter_typesrr(r(r)r s(              zTransformer.sinccCsZt|r|dkr td|dks|dkrtdd|dg}|j||jd|S)a_Adjust the audio speed (pitch and tempo together). Technically, the speed effect only changes the sample rate information, leaving the samples themselves untouched. The rate effect is invoked automatically to resample to the output sample rate, using its default quality/speed. For higher quality or higher speed resampling, in addition to the speed effect, specify the rate effect with the desired quality option. Parameters ---------- factor : float The ratio of the new speed to the old speed. For ex. 1.1 speeds up the audio by 10%; 0.9 slows it down by 10%. Note - this argument is the inverse of what is passed to the sox stretch effect for consistency with speed. See Also -------- rate, tempo, pitch r factor must be a positive numberrrz8Using an extreme factor. Quality of results will be poorr\rK)rr3rrr"rOr#r6r=r(r(r)r\ s   zTransformer.speedscalermsc Csgd}|durt|r|dkrtd|d|dg|r$|d|j|d|d d \}}}i}|d }|D]} | } | sBq9| d } d | dd } | || d<q9|S)aDisplay time and frequency domain statistical information about the audio. Audio is passed unmodified through the SoX processing chain. Unlike other Transformer methods, this does not modify the transformer effects chain. Instead it computes statistics on the output file that would be created if the build command were invoked. Note: The file is downmixed to mono prior to computation. Parameters ---------- input_filepath : str Path to input file to compute stats on. scale : float or None, default=None If not None, scales the input by the given scale factor. rms : bool, default=False If True, scales all values by the average rms amplitude. Returns ------- stat_dict : dict Dictionary of statistics. See Also -------- stats, power_spectrum, sox.file_info )r<rstatNrz scale must be a positive number.rrKz-rmsrlTrnro r_rs:)rr3rOr6r{splitrvstrip) r'rirrrr stat_output stat_dictlinesline split_linevaluerr(r(r)r; s(   zTransformer.statc Cspgd}|j|d|dd\}}}g}|d}|D]}|}t|dkr&q|\} } |t| t| gq|S)aCalculates the power spectrum (4096 point DFT). This method internally invokes the stat command with the -freq option. Note: The file is downmixed to mono prior to computation. Parameters ---------- input_filepath : str Path to input file to compute stats on. Returns ------- power_spectrum : list List of frequency (Hz), amplitude pairs. See Also -------- stat, stats, sox.file_info )r<rrz-freqrlTrrr)r{rrgr6float) r'rirrrpower_spectrumrrrfreqampr(r(r)rs s   zTransformer.power_spectrumc Cstgd}|j|d|dd\}}}i}|d}|D]}|}t|dkr&q|d} d|d d} | || <q|S) aDisplay time domain statistical information about the audio channels. Audio is passed unmodified through the SoX processing chain. Statistics are calculated and displayed for each audio channel Unlike other Transformer methods, this does not modify the transformer effects chain. Instead it computes statistics on the output file that would be created if the build command were invoked. Note: The file is downmixed to mono prior to computation. Parameters ---------- input_filepath : str Path to input file to compute stats on. Returns ------- stats_dict : dict List of frequency (Hz), amplitude pairs. See Also -------- stat, sox.file_info )r<rstatsrlTrrrr_rsN)r{rrgrv) r'rirr stats_output stats_dictrrrrrr(r(r)r s    zTransformer.statsrwindowcCst|r|dkr td|dks|dkrtdt|ddkr&tdt|r.|dkr2td d |d |d g}|j||jd |S) a4Change the audio duration (but not its pitch). **Unless factor is close to 1, use the tempo effect instead.** This effect is broadly equivalent to the tempo effect with search set to zero, so in general, its results are comparatively poor; it is retained as it can sometimes out-perform tempo for small factors. Parameters ---------- factor : float The ratio of the new tempo to the old tempo. For ex. 1.1 speeds up the tempo by 10%; 0.9 slows it down by 10%. Note - this argument is the inverse of what is passed to the sox stretch effect for consistency with tempo. window : float, default=20 Window size in miliseconds See Also -------- tempo, speed, pitch rrrrHUsing an extreme time stretching factor. Quality of results will be poorrrezAFor this stretch factor, the tempo effect has better performance.z!window must be a positive number.stretchrK) rr3rrabsr"rOr#r6)r'r9rrr(r(r)r s$  zTransformer.stretchcCr0)aSwap stereo channels. If the input is not stereo, pairs of channels are swapped, and a possible odd last channel passed through. E.g., for seven channels, the output order will be 2, 1, 4, 3, 6, 5, 7. See Also ---------- remix swapr2r3r(r(r)r s  zTransformer.swap audio_type)rrrNcCst|r|dkr td|dks|dkrtdt|ddkr&td|d vr.td t|ts7td d g}|rA|d |durM|d|||d|j ||j d |S)aTime stretch audio without changing pitch. This effect uses the WSOLA algorithm. The audio is chopped up into segments which are then shifted in the time domain and overlapped (cross-faded) at points where their waveforms are most similar as determined by measurement of least squares. Parameters ---------- factor : float The ratio of new tempo to the old tempo. For ex. 1.1 speeds up the tempo by 10%; 0.9 slows it down by 10%. audio_type : str Type of audio, which optimizes algorithm parameters. One of: * m : Music, * s : Speech, * l : Linear (useful when factor is close to 1), quick : bool, default=False If True, this effect will run faster but with lower sound quality. See Also -------- stretch, speed, pitch rrrrrrrezCFor this stretch factor, the stretch effect has better performance.)NrrrNz1audio_type must be one of None, 'm', 's', or 'l'.rtemporNr^rK) rr3rrrr1r2r6r"rOr#)r'r9rrrr(r(r)r s2    zTransformer.tempop@cCr) u7Boost or cut the treble (lower) frequencies of the audio using a two-pole shelving filter with a response similar to that of a standard hi-fi’s tone-controls. This is also known as shelving equalisation. The filters are described in detail in http://musicdsp.org/files/Audio-EQ-Cookbook.txt Parameters ---------- gain_db : float The gain at the Nyquist frequency. For a large cut use -20, for a large boost use 20. frequency : float, default=100.0 The filter's cutoff frequency in Hz. slope : float, default=0.5 The steepness of the filter's shelf transition. For a gentle slope use 0.3, and use 1.0 for a steep slope. See Also -------- bass, equalizer rrrrrtreblerKrrrr(r(r)rI s   zTransformer.trebleD@cCsft|r|dkr tdt|r|dks|dkrtdd|d|dg}|j||jd|S)a>Apply a tremolo (low frequency amplitude modulation) effect to the audio. The tremolo frequency in Hz is giv en by speed, and the depth as a percentage by depth (default 40). Parameters ---------- speed : float Tremolo speed in Hz. depth : float Tremolo depth as a percentage of the total amplitude. See Also -------- flanger Examples -------- >>> tfm = sox.Transformer() For a growl-type effect >>> tfm.tremolo(speed=100.0) rrr$z.depth must be a positive number less than 100.tremolorKr)r'r\rYrr(r(r)r v s  zTransformer.tremolo start_timeend_timecCst|r|dkr tdd|dg}|dur3t|r|dkr"td||kr*td|||d|j||jd|S)aExcerpt a clip from an audio file, given the start timestamp and end timestamp of the clip within the file, expressed in seconds. If the end timestamp is set to `None` or left unspecified, it defaults to the duration of the audio file. Parameters ---------- start_time : float Start time of the clip (seconds) end_time : float or None, default=None End time of the clip (seconds) rz%start_time must be a positive number.trimrKNz#end_time must be a positive number.z)start_time must be smaller than end_time.rt)r'r r rr(r(r)r  s   zTransformer.trimcCr:)aUpsample the signal by an integer factor: zero-value samples are inserted between each pair of input samples. As a result, the original spectrum is replicated into the new frequency space (imaging) and attenuated. The upsample effect is typically used in combination with filtering effects. Parameters ---------- factor : int, default=2 Integer upsampling factor. See Also -------- rate, downsample r r;upsamplerr=r(r(r)r s    zTransformer.upsample@rr)r r_activity_thresholdmin_activity_durationinitial_search_buffermax_gap initial_padc Cs|dvrtdt|tstdt|stdt|r!|dkr%tdt|r-|dkr1tdt|r9|dkr=tdt|rE|dkrItd g}|rR|d |d kr[|d |d d|dd|dd|dd|dd|dg |d kr~|d |j||jd |S)aVoice Activity Detector. Attempts to trim silence and quiet background sounds from the ends of recordings of speech. The algorithm currently uses a simple cepstral power measurement to detect voice, so may be fooled by other things, especially music. The effect can trim only from the front of the audio, so in order to trim from the back, the reverse effect must also be used. Parameters ---------- location : 1 or -1, default=1 If 1, trims silence from the beginning If -1, trims silence from the end normalize : bool, default=True If true, normalizes audio before processing. activity_threshold : float, default=7.0 The measurement level used to trigger activity detection. This may need to be cahnged depending on the noise level, signal level, and other characteristics of the input audio. min_activity_duration : float, default=0.25 The time constant (in seconds) used to help ignore short bursts of sound. initial_search_buffer : float, default=1.0 The amount of audio (in seconds) to search for quieter/shorter bursts of audio to include prior to the detected trigger point. max_gap : float, default=0.25 The allowed gap (in seconds) between quiteter/shorter bursts of audio to include prior to the detected trigger point initial_pad : float, default=0.0 The amount of audio (in seconds) to preserve before the trigger point and any found quieter/shorter bursts. See Also -------- silence Examples -------- >>> tfm = sox.Transformer() Remove silence from the beginning of speech >>> tfm.vad(initial_pad=0.3) Remove silence from the end of speech >>> tfm.vad(location=-1, initial_pad=0.2) )r_r zlocation must be -1 or 1.znormalize muse be a boolean.z$activity_threshold must be a number.rz/min_activity_duration must be a positive numberz/initial_search_buffer must be a positive numberz"max_gap must be a positive number.z&initial_pad must be a positive number.rr_rPvadrIrKz-Trz-gr)r3r1r2rr6rOr"r#) r'rrgrrrrrrr(r(r)r s@9      zTransformer.vadr gain_typer limiter_gaincCs t|std|durt|r|dks|dkrtd|dvr(|dkr(tddg}||d |d kr<|d n|d krF|d n|d krP|d ntd|durw|dvrh|dkrh||d n|d krw|dkrw||d |j||jd|S)a^Apply an amplification or an attenuation to the audio signal. Parameters ---------- gain : float Interpreted according to the given `gain_type`. If `gain_type' = 'amplitude', `gain' is a positive amplitude ratio. If `gain_type' = 'power', `gain' is a power (voltage squared). If `gain_type' = 'db', `gain' is in decibels. gain_type : string, default='amplitude' Type of gain. One of: - 'amplitude' - 'power' - 'db' limiter_gain : float or None, default=None If specified, a limiter is invoked on peaks greater than `limiter_gain' to prevent clipping. `limiter_gain` should be a positive value much less than 1. See Also -------- gain, compand zgain must be a number.Nrr z2limiter gain must be a positive number less than 1)rrz9If gain_type = amplitude or power, gain must be positive.volrKrrrdBz.gain_type must be one of amplitude power or dbrt)r'rkrrrr(r(r)r:s:     zTransformer.vol)FFFFr)NNNNNF)NNNNNNT)NNNN)r)rF)rr)rr)rrrNNNNN)r")NNN)r,)r)r,r,r)rrrrVrrWrrX)r,TFN)rnrr )rzr{)r)r)rr)r,r,)rrrrrr)F)rM)NN)r )r}r}r$r$rrF)rrereF)rrrNN)NF)r)rr)rr )r Trrrrr,)rN)X__name__ __module__ __qualname____doc__r*r2rGr%rHrQrrVrr rSrWrYr[r]rlrrrr{rarbr|rrrrrrrrr<rrrrr%r}r/r1r5r<r>rDrFrHrOrUrfrkrsrwryr~rrrrrrrrrr:rrrrrPrrr\rrrrrrrr r rrrr(r(r(r)r%s  H*# P-' S7  y  S    * +  1 c+      V ' L K )  8 C  B . ,(  '   &' ! @-  * R Q Q' 8&+ 2 C -"( b r)#rrrpathlibrtypingrrrrrnumpyratyping_extensionsrrr corer r r rrrrlogrr4rrrrrdGainTyperr(r(r(r)s.