To install Stable-ts without Whisper as a dependency:

pip install -U stable-ts-whisperless

To install the latest Whisperless commit:

pip install -U git+https://github.com/jianfch/stable-ts.git@whisperless

stable-ts audio.mp3 -o audio.srt

Load an instance if :class:`whisper.model.Whisper`.

Parameters
----------
name : {'tiny', 'tiny.en', 'base', 'base.en', 'small', 'small.en', 'medium', 'medium.en', 'large-v1',
    'large-v2', 'large-v3', or 'large'}
    One of the official model names listed by :func:`whisper.available_models`, or
    path to a model checkpoint containing the model dimensions and the model state_dict.
device : str or torch.device, optional
    PyTorch device to put the model into.
download_root : str, optional
    Path to download the model files; by default, it uses "~/.cache/whisper".
in_memory : bool, default False
    Whether to preload the model weights into host memory.
cpu_preload : bool, default True
    Load model into CPU memory first then move model to specified device
    to reduce GPU memory usage when loading model
dq : bool, default False
    Whether to apply Dynamic Quantization to model to reduced memory usage and increase inference speed
    but at the cost of a slight decrease in accuracy. Only for CPU.
engine : str, optional
    Engine for Dynamic Quantization.

Returns
-------
model : "Whisper"
    The Whisper ASR model instance.

Notes
-----
The overhead from ``dq = True`` might make inference slower for models smaller than 'large'.

Transcribe audio using Whisper.

This is a modified version of :func:`whisper.transcribe.transcribe` with slightly different decoding logic while
allowing additional preprocessing and postprocessing. The preprocessing performed on the audio includes:
voice isolation / noise removal and low/high-pass filter. The postprocessing performed on the transcription
result includes: adjusting timestamps with VAD and custom regrouping segments based punctuation and speech gaps.

Parameters
----------
model : whisper.model.Whisper
    An instance of Whisper ASR model.
audio : str or numpy.ndarray or torch.Tensor or bytes or AudioLoader
    Path/URL to the audio file, the audio waveform, or bytes of audio file or
    instance of :class:`stable_whisper.audio.AudioLoader`.
    If audio is :class:`numpy.ndarray` or :class:`torch.Tensor`, the audio must be already at sampled to 16kHz.
verbose : bool or None, default False
    Whether to display the text being decoded to the console.
    Displays all the details if ``True``. Displays progressbar if ``False``. Display nothing if ``None``.
temperature : float or iterable of float, default (0.0, 0.2, 0.4, 0.6, 0.8, 1.0)
    Temperature for sampling. It can be a tuple of temperatures, which will be successfully used
    upon failures according to either ``compression_ratio_threshold`` or ``logprob_threshold``.
compression_ratio_threshold : float, default 2.4
    If the gzip compression ratio is above this value, treat as failed.
logprob_threshold : float, default -1
    If the average log probability over sampled tokens is below this value, treat as failed
no_speech_threshold : float, default 0.6
    If the no_speech probability is higher than this value AND the average log probability
    over sampled tokens is below ``logprob_threshold``, consider the segment as silent
condition_on_previous_text : bool, default True
    If ``True``, the previous output of the model is provided as a prompt for the next window;
    disabling may make the text inconsistent across windows, but the model becomes less prone to
    getting stuck in a failure loop, such as repetition looping or timestamps going out of sync.
initial_prompt : str, optional
    Text to provide as a prompt for the first window. This can be used to provide, or
    "prompt-engineer" a context for transcription, e.g. custom vocabularies or proper nouns
    to make it more likely to predict those word correctly.
word_timestamps : bool, default True
    Extract word-level timestamps using the cross-attention pattern and dynamic time warping,
    and include the timestamps for each word in each segment.
    Disabling this will prevent segments from splitting/merging properly.
regroup : bool or str, default True, meaning the default regroup algorithm
    String for customizing the regrouping algorithm. False disables regrouping.
    Ignored if ``word_timestamps = False``.
suppress_silence : bool, default True
    Whether to enable timestamps adjustments based on the detected silence.
suppress_word_ts : bool, default True
    Whether to adjust word timestamps based on the detected silence. Only enabled if ``suppress_silence = True``.
use_word_position : bool, default True
    Whether to use position of the word in its segment to determine whether to keep end or start timestamps if
    adjustments are required. If it is the first word, keep end. Else if it is the last word, keep the start.
q_levels : int, default 20
    Quantization levels for generating timestamp suppression mask; ignored if ``vad = true``.
    Acts as a threshold to marking sound as silent.
    Fewer levels will increase the threshold of volume at which to mark a sound as silent.
k_size : int, default 5
    Kernel size for avg-pooling waveform to generate timestamp suppression mask; ignored if ``vad = true``.
    Recommend 5 or 3; higher sizes will reduce detection of silence.
denoiser : str, optional
    String of the denoiser to use for preprocessing ``audio``.
    See ``stable_whisper.audio.SUPPORTED_DENOISERS`` for supported denoisers.
denoiser_options : dict, optional
    Options to use for ``denoiser``.
vad : bool or dict, default False
    Whether to use Silero VAD to generate timestamp suppression mask.
    Instead of ``True``, using a dict of keyword arguments will load the VAD with the arguments.
    Silero VAD requires PyTorch 1.12.0+. Official repo, https://github.com/snakers4/silero-vad.
vad_threshold : float, default 0.35
    Threshold for detecting speech with Silero VAD. Low threshold reduces false positives for silence detection.
min_word_dur : float or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Shortest duration each word is allowed to reach for silence suppression.
min_silence_dur : float, optional
    Shortest duration of silence allowed for silence suppression.
nonspeech_error : float, default 0.1
    Relative error of non-speech sections that appear in between a word for silence suppression.
only_voice_freq : bool, default False
    Whether to only use sound between 200 - 5000 Hz, where majority of human speech are.
prepend_punctuations : str or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Punctuations to prepend to next word.
append_punctuations : str or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Punctuations to append to previous word.
stream : bool or None, default None
    Whether to loading ``audio`` in chunks of 30 seconds until the end of file/stream.
    If ``None`` and ``audio`` is a string then set to ``True`` else ``False``.
mel_first : bool, optional
    Process entire audio track into log-Mel spectrogram first instead in chunks.
    Used if odd behavior seen in stable-ts but not in whisper, but use significantly more memory for long audio.
split_callback : Callable, optional
    Custom callback for grouping tokens up with their corresponding words.
    The callback must take two arguments, list of tokens and tokenizer.
    The callback returns a tuple with a list of words and a corresponding nested list of tokens.
suppress_ts_tokens : bool, default False
    Whether to suppress timestamp tokens during inference for timestamps are detected at silent.
    Reduces hallucinations in some cases, but also prone to ignore disfluencies and repetitions.
    This option is ignored if ``suppress_silence = False``.
gap_padding : str, default ' ...'
    Padding prepend to each segments for word timing alignment.
    Used to reduce the probability of model predicting timestamps earlier than the first utterance.
only_ffmpeg : bool, default False
    Whether to use only FFmpeg (instead of not yt-dlp) for URls
max_instant_words : float, default 0.5
    If percentage of instantaneous words in a segment exceed this amount, the segment is removed.
avg_prob_threshold: float or None, default None
    Transcribe the gap after the previous word and if the average word proababiliy of a segment falls below this
    value, discard the segment. If ``None``, skip transcribing the gap to reduce chance of timestamps starting
    before the next utterance.
nonspeech_skip : float or None, default None
    Skip non-speech sections that are equal or longer than this duration in seconds. Disable skipping if ``None``.
    Reduce text and timing hallucinations in non-speech sections but may increase processing time.
progress_callback : Callable, optional
    A function that will be called when transcription progress is updated.
    The callback need two parameters.
    The first parameter is a float for seconds of the audio that has been transcribed.
    The second parameter is a float for total duration of audio in seconds.
ignore_compatibility : bool, default False
    Whether to ignore warnings for compatibility issues with the detected Whisper version.
extra_models : list of whisper.model.Whisper, optional
    List of additional Whisper model instances to use for computing word-timestamps along with ``model``.
dynamic_heads : bool or int or str, optional
    Whether to find optimal cross-attention heads during runtime instead of using the predefined heads for 
    word-timestamp extraction. Specify the number of heads or `True` for default of 6 heads.
    To specify number of iterations for finding the optimal heads,
    use string with "," to separate heads and iterations (e.g. "8,3" for 8 heads and 3 iterations).
decode_options
    Keyword arguments to construct class:`whisper.decode.DecodingOptions` instances.

Returns
-------
stable_whisper.result.WhisperResult
    All timestamps, words, probabilities, and other data from the transcription of ``audio``.

See Also
--------
stable_whisper.non_whisper.transcribe_any : Return :class:`stable_whisper.result.WhisperResult` containing all the
    data from transcribing audio with unmodified :func:`whisper.transcribe.transcribe` with preprocessing and
    postprocessing.
stable_whisper.whisper_word_level.faster_whisper.faster_transcribe : Return
    :class:`stable_whisper.result.WhisperResult` containing all the data from transcribing audio with
    :meth:`faster_whisper.WhisperModel.transcribe` with preprocessing and postprocessing.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.transcribe('audio.mp3', vad=True)
>>> result.to_srt_vtt('audio.srt')
Saved: audio.srt

Transcribe audio using Whisper.

This is uses the original whisper transcribe function, :func:`whisper.transcribe.transcribe`, while still allowing
additional preprocessing and postprocessing. The preprocessing performed on the audio includes: voice isolation /
noise removal and low/high-pass filter. The postprocessing performed on the transcription result includes:
adjusting timestamps with VAD and custom regrouping segments based punctuation and speech gaps.

Parameters
----------
model : whisper.model.Whisper
    An instance of Whisper ASR model.
audio : str or numpy.ndarray or torch.Tensor or bytes
    Path/URL to the audio file, the audio waveform, or bytes of audio file.
    If audio is ``numpy.ndarray`` or ``torch.Tensor``, the audio must be already at sampled to 16kHz.
verbose : bool or None, default False
    Whether to display the text being decoded to the console.
    Displays all the details if ``True``. Displays progressbar if ``False``. Display nothing if ``None``.
word_timestamps : bool, default True
    Extract word-level timestamps using the cross-attention pattern and dynamic time warping,
    and include the timestamps for each word in each segment.
    Disabling this will prevent segments from splitting/merging properly.
regroup : bool or str, default True, meaning the default regroup algorithm
    String for customizing the regrouping algorithm. False disables regrouping.
    Ignored if ``word_timestamps = False``.
suppress_silence : bool, default True
    Whether to enable timestamps adjustments based on the detected silence.
suppress_word_ts : bool, default True
    Whether to adjust word timestamps based on the detected silence. Only enabled if ``suppress_silence = True``.
use_word_position : bool, default True
    Whether to use position of the word in its segment to determine whether to keep end or start timestamps if
    adjustments are required. If it is the first word, keep end. Else if it is the last word, keep the start.
q_levels : int, default 20
    Quantization levels for generating timestamp suppression mask; ignored if ``vad = true``.
    Acts as a threshold to marking sound as silent.
    Fewer levels will increase the threshold of volume at which to mark a sound as silent.
k_size : int, default 5
    Kernel size for avg-pooling waveform to generate timestamp suppression mask; ignored if ``vad = true``.
    Recommend 5 or 3; higher sizes will reduce detection of silence.
denoiser : str, optional
    String of the denoiser to use for preprocessing ``audio``.
    See ``stable_whisper.audio.SUPPORTED_DENOISERS`` for supported denoisers.
denoiser_options : dict, optional
    Options to use for ``denoiser``.
vad : bool or dict, default False
    Whether to use Silero VAD to generate timestamp suppression mask.
    Instead of ``True``, using a dict of keyword arguments will load the VAD with the arguments.
    Silero VAD requires PyTorch 1.12.0+. Official repo, https://github.com/snakers4/silero-vad.
vad_threshold : float, default 0.35
    Threshold for detecting speech with Silero VAD. Low threshold reduces false positives for silence detection.
min_word_dur : float, default 0.1
    Shortest duration each word is allowed to reach for silence suppression.
min_silence_dur : float, optional
    Shortest duration of silence allowed for silence suppression.
nonspeech_error : float, default 0.1
    Relative error of non-speech sections that appear in between a word for silence suppression.
only_voice_freq : bool, default False
    Whether to only use sound between 200 - 5000 Hz, where majority of human speech are.
only_ffmpeg : bool, default False
    Whether to use only FFmpeg (instead of not yt-dlp) for URls
options
    Additional options used for :func:`whisper.transcribe.transcribe` and
    :func:`stable_whisper.non_whisper.transcribe_any`.
Returns
-------
stable_whisper.result.WhisperResult
    All timestamps, words, probabilities, and other data from the transcription of ``audio``.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.transcribe_minimal('audio.mp3', vad=True)
>>> result.to_srt_vtt('audio.srt')
Saved: audio.srt

Use with Faster-Whisper:

pip install -U stable-ts[fw]

• Refinement is slower on Faster-Whisper models than on vanilla models (i.e. ones loaded with stable_whisper.load_model())

model = stable_whisper.load_faster_whisper('base')
result = model.transcribe('audio.mp3')

# faster transcription with `BatchedInferencePipeline`
result = model.transcribe('audio.mp3', batch_size=16)

# For versions < 2.18.0:
result = model.transcribe_stable('audio.mp3')

stable-ts audio.mp3 -o audio.srt -fw

Docstring:

Load an instance of :class:`faster_whisper.WhisperModel`.

Parameters
----------
model_size_or_path : {'tiny', 'tiny.en', 'base', 'base.en', 'small', 'small.en', 'medium', 'medium.en', 'large-v1',
    'large-v2', 'large-v3', or 'large'}
    Size of the model.

model_init_options
    Additional options to use for initialization of :class:`faster_whisper.WhisperModel`.

Returns
-------
faster_whisper.WhisperModel
    A modified instance of :class:`faster_whisper.WhisperModel`.

Transcribe audio using faster-whisper (https://github.com/guillaumekln/faster-whisper).

This is uses the transcribe method from faster-whisper, :meth:`faster_whisper.WhisperModel.transcribe`, while
still allowing additional preprocessing and postprocessing. The preprocessing performed on the audio includes:
voice isolation / noise removal and low/high-pass filter. The postprocessing performed on the
transcription result includes: adjusting timestamps with VAD and custom regrouping segments based punctuation
and speech gaps.

Parameters
----------
model : faster_whisper.WhisperModel
    The faster-whisper ASR model instance.
audio : str or numpy.ndarray or torch.Tensor or bytes
    Path/URL to the audio file, the audio waveform, or bytes of audio file.
    If audio is :class:`numpy.ndarray` or :class:`torch.Tensor`, the audio must be already at sampled to 16kHz.
verbose : bool or None, default False
    Whether to display the text being decoded to the console.
    Displays all the details if ``True``. Displays progressbar if ``False``. Display nothing if ``None``.
word_timestamps : bool, default True
    Extract word-level timestamps using the cross-attention pattern and dynamic time warping,
    and include the timestamps for each word in each segment.
    Disabling this will prevent segments from splitting/merging properly.
regroup : bool or str, default True, meaning the default regroup algorithm
    String for customizing the regrouping algorithm. False disables regrouping.
    Ignored if ``word_timestamps = False``.
suppress_silence : bool, default True
    Whether to enable timestamps adjustments based on the detected silence.
suppress_word_ts : bool, default True
    Whether to adjust word timestamps based on the detected silence. Only enabled if ``suppress_silence = True``.
use_word_position : bool, default True
    Whether to use position of the word in its segment to determine whether to keep end or start timestamps if
    adjustments are required. If it is the first word, keep end. Else if it is the last word, keep the start.
q_levels : int, default 20
    Quantization levels for generating timestamp suppression mask; ignored if ``vad = true``.
    Acts as a threshold to marking sound as silent.
    Fewer levels will increase the threshold of volume at which to mark a sound as silent.
k_size : int, default 5
    Kernel size for avg-pooling waveform to generate timestamp suppression mask; ignored if ``vad = true``.
    Recommend 5 or 3; higher sizes will reduce detection of silence.
denoiser : str, optional
    String of the denoiser to use for preprocessing ``audio``.
    See ``stable_whisper.audio.SUPPORTED_DENOISERS`` for supported denoisers.
denoiser_options : dict, optional
    Options to use for ``denoiser``.
vad : bool or dict, default False
    Whether to use Silero VAD to generate timestamp suppression mask.
    Instead of ``True``, using a dict of keyword arguments will load the VAD with the arguments.
    Silero VAD requires PyTorch 1.12.0+. Official repo, https://github.com/snakers4/silero-vad.
vad_threshold : float, default 0.35
    Threshold for detecting speech with Silero VAD. Low threshold reduces false positives for silence detection.
min_word_dur : float or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Shortest duration each word is allowed to reach for silence suppression.
min_silence_dur : float, optional
    Shortest duration of silence allowed for silence suppression.
nonspeech_error : float, default 0.3
    Relative error of non-speech sections that appear in between a word for silence suppression.
only_voice_freq : bool, default False
    Whether to only use sound between 200 - 5000 Hz, where majority of human speech are.
only_ffmpeg : bool, default False
    Whether to use only FFmpeg (instead of not yt-dlp) for URls
check_sorted : bool, default True
    Whether to raise an error when timestamps returned by faster-whipser are not in ascending order.
progress_callback : Callable, optional
    A function that will be called when transcription progress is updated.
    The callback need two parameters.
    The first parameter is a float for seconds of the audio that has been transcribed.
    The second parameter is a float for total duration of audio in seconds.
options
    Additional options used for :meth:`faster_whisper.WhisperModel.transcribe` and
    :func:`stable_whisper.non_whisper.transcribe_any`.

Returns
-------
stable_whisper.result.WhisperResult
    All timestamps, words, probabilities, and other data from the transcription of ``audio``.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_faster_whisper('base')
>>> result = model.transcribe('audio.mp3', vad=True)
>>> result.to_srt_vtt('audio.srt')
Saved: audio.srt

Transcribe up to 9x faster with Hugging Face Transformer:

pip install -U stable-ts[hf]

model = stable_whisper.load_hf_whisper('base')
result = model.transcribe('audio.mp3')

Supports the various versions on Hugging Face:

model = stable_whisper.load_hf_whisper('openai/whisper-base.en')

stable-ts audio.mp3 -o audio.srt -hw

Transcribe faster on Apple devices with MLX Whisper:

pip install -U stable-ts[mlx]

import stable_whisper

model = stable_whisper.load_mlx_whisper('base')
result = model.transcribe('audio.mp3')

stable-ts audio.mp3 -o audio.srt -mlx

Generate SRT/VTT from ``result`` to display segment-level and/or word-level timestamp.

Parameters
----------
result : dict or list or stable_whisper.result.WhisperResult
    Result of transcription.
filepath : str, default None, meaning content will be returned as a ``str``
    Path to save file.
segment_level : bool, default True
    Whether to use segment-level timestamps in output.
word_level : bool, default True
    Whether to use word-level timestamps in output.
min_dur : float, default 0.2
    Minimum duration allowed for any word/segment before the word/segments are merged with adjacent word/segments.
tag: tuple of (str, str), default None, meaning ('<font color="#00ff00">', '</font>') if SRT else ('<u>', '</u>')
    Tag used to change the properties a word at its timestamp.
vtt : bool, default None, meaning determined by extension of ``filepath`` or ``False`` if no valid extension.
    Whether to output VTT.
strip : bool, default True
    Whether to remove spaces before and after text on each segment for output.
reverse_text: bool or tuple, default False
    Whether to reverse the order of words for each segment or provide the ``prepend_punctuations`` and
    ``append_punctuations`` as tuple pair instead of ``True`` which is for the default punctuations.

Returns
-------
str
    String of the content if ``filepath`` is ``None``.

Notes
-----
``reverse_text`` will not fix RTL text not displaying tags properly which is an issue with some video player. VLC
seems to not suffer from this issue.

Examples
--------
&gt;&gt;&gt; import stable_whisper
&gt;&gt;&gt; model = stable_whisper.load_model('base')
&gt;&gt;&gt; result = model.transcribe('audio.mp3')
&gt;&gt;&gt; result.to_srt_vtt('audio.srt')
Saved: audio.srt

Generate Advanced SubStation Alpha (ASS) file from ``result`` to display segment-level and/or word-level timestamp.

Parameters
----------
result : dict or list or stable_whisper.result.WhisperResult
    Result of transcription.
filepath : str, default None, meaning content will be returned as a ``str``
    Path to save file.
segment_level : bool, default True
    Whether to use segment-level timestamps in output.
word_level : bool, default True
    Whether to use word-level timestamps in output.
min_dur : float, default 0.2
    Minimum duration allowed for any word/segment before the word/segments are merged with adjacent word/segments.
tag: tuple of (str, str) or int, default None, meaning use default highlighting
    Tag used to change the properties a word at its timestamp. -1 for individual word highlight tag.
font : str, default `Arial`
    Word font.
font_size : int, default 48
    Word font size.
strip : bool, default True
    Whether to remove spaces before and after text on each segment for output.
highlight_color : str, default '00ff00'
    Hexadecimal of the color use for default highlights as ''.
karaoke : bool, default False
    Whether to use progressive filling highlights (for karaoke effect).
reverse_text: bool or tuple, default False
    Whether to reverse the order of words for each segment or provide the ``prepend_punctuations`` and
    ``append_punctuations`` as tuple pair instead of ``True`` which is for the default punctuations.
kwargs:
    Format styles:
    'Name', 'Fontname', 'Fontsize', 'PrimaryColour', 'SecondaryColour', 'OutlineColour', 'BackColour', 'Bold',
    'Italic', 'Underline', 'StrikeOut', 'ScaleX', 'ScaleY', 'Spacing', 'Angle', 'BorderStyle', 'Outline',
    'Shadow', 'Alignment', 'MarginL', 'MarginR', 'MarginV', 'Encoding'

Returns
-------
str
    String of the content if ``filepath`` is ``None``.

Notes
-----
``reverse_text`` will not fix RTL text not displaying tags properly which is an issue with some video player. VLC
seems to not suffer from this issue.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.transcribe('audio.mp3')
>>> result.to_ass('audio.ass')
Saved: audio.ass

Generate TSV from ``result`` to display segment-level and/or word-level timestamp.

Parameters
----------
result : dict or list or stable_whisper.result.WhisperResult
    Result of transcription.
filepath : str, default None, meaning content will be returned as a ``str``
    Path to save file.
segment_level : bool, default True
    Whether to use segment-level timestamps in output.
word_level : bool, default True
    Whether to use word-level timestamps in output.
min_dur : float, default 0.2
    Minimum duration allowed for any word/segment before the word/segments are merged with adjacent word/segments.
strip : bool, default True
    Whether to remove spaces before and after text on each segment for output.
reverse_text: bool or tuple, default False
    Whether to reverse the order of words for each segment or provide the ``prepend_punctuations`` and
    ``append_punctuations`` as tuple pair instead of ``True`` which is for the default punctuations.

Returns
-------
str
    String of the content if ``filepath`` is ``None``.

Notes
-----
``reverse_text`` will not fix RTL text not displaying tags properly which is an issue with some video player. VLC
seems to not suffer from this issue.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.transcribe('audio.mp3')
>>> result.to_tsv('audio.tsv')
Saved: audio.tsv

Generate plain-text without timestamps from ``result``.

Parameters
----------
result : dict or list or stable_whisper.result.WhisperResult
    Result of transcription.
filepath : str, default None, meaning content will be returned as a ``str``
    Path to save file.
min_dur : float, default 0.2
    Minimum duration allowed for any word/segment before the word/segments are merged with adjacent word/segments.
strip : bool, default True
    Whether to remove spaces before and after text on each segment for output.
reverse_text: bool or tuple, default False
    Whether to reverse the order of words for each segment or provide the ``prepend_punctuations`` and
    ``append_punctuations`` as tuple pair instead of ``True`` which is for the default punctuations.

Returns
-------
str
    String of the content if ``filepath`` is ``None``.

Notes
-----
``reverse_text`` will not fix RTL text not displaying tags properly which is an issue with some video player. VLC
seems to not suffer from this issue.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.transcribe('audio.mp3')
>>> result.to_txt('audio.txt')
Saved: audio.txt

Save ``result`` as JSON file to ``path``.

Parameters
----------
result : dict or list or stable_whisper.result.WhisperResult
    Result of transcription.
path : str
    Path to save file.
ensure_ascii : bool, default False
    Whether to escape non-ASCII characters.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.transcribe('audio.mp3')
>>> result.save_as_json('audio.json')
Saved: audio.json

--segment_level true + --word_level true

stable-ts audio.mp3 -o audio.json

stable-ts audio.json -o audio.srt

stable-ts audio.mp3 --align text.txt --language en

--align can also be a JSON file of a result

Align plain text or tokens with audio at word-level.

Since this is significantly faster than transcribing, it is a more efficient method for testing various settings
without re-transcribing. This is also useful for timing a more correct transcript than one that Whisper can produce.

Parameters
----------
model : "Whisper"
    The Whisper ASR model modified instance
audio : str or numpy.ndarray or torch.Tensor or bytes or AudioLoader
    Path/URL to the audio file, the audio waveform, or bytes of audio file or
    instance of :class:`stable_whisper.audio.AudioLoader`.
    If audio is :class:`numpy.ndarray` or :class:`torch.Tensor`, the audio must be already at sampled to 16kHz.
text : str or list of int or stable_whisper.result.WhisperResult
    String of plain-text, list of tokens, or instance of :class:`stable_whisper.result.WhisperResult`.
language : str, default None, uses ``language`` in ``text`` if it is a :class:`stable_whisper.result.WhisperResult`
    Language of ``text``. Required if ``text`` does not contain ``language``.
remove_instant_words : bool, default False
    Whether to truncate any words with zero duration.
token_step : int, default 100
    Max number of tokens to align each pass. Use higher values to reduce chance of misalignment.
original_split : bool, default False
    Whether to preserve the original segment groupings. Segments are split by line breaks if ``text`` is plain-text.
max_word_dur : float or None, default 3.0
    Global maximum word duration in seconds. Re-align words that exceed the global maximum word duration.
word_dur_factor : float or None, default 2.0
    Factor to compute the Local maximum word duration, which is ``word_dur_factor`` * local medium word duration.
    Words that need re-alignment, are re-algined with duration <= local/global maximum word duration.
nonspeech_skip : float or None, default 5.0
    Skip non-speech sections that are equal or longer than this duration in seconds. Disable skipping if ``None``.
fast_mode : bool, default False
    Whether to speed up alignment by re-alignment with local/global maximum word duration.
    ``True`` tends produce better timestamps when ``text`` is accurate and there are no large speechless gaps.
tokenizer : "Tokenizer", default None, meaning a new tokenizer is created according ``language`` and ``model``
    A tokenizer to used tokenizer text and detokenize tokens.
stream : bool or None, default None
    Whether to loading ``audio`` in chunks of 30 seconds until the end of file/stream.
    If ``None`` and ``audio`` is a string then set to ``True`` else ``False``.
failure_threshold : float, optional
    Abort alignment when percentage of words with zero duration exceeds ``failure_threshold``.
verbose : bool or None, default False
    Whether to display the text being decoded to the console.
    Displays all the details if ``True``. Displays progressbar if ``False``. Display nothing if ``None``.
regroup : bool or str, default True, meaning the default regroup algorithm
    String for customizing the regrouping algorithm. False disables regrouping.
    Ignored if ``word_timestamps = False``.
suppress_silence : bool, default True
    Whether to enable timestamps adjustments based on the detected silence.
suppress_word_ts : bool, default True
    Whether to adjust word timestamps based on the detected silence. Only enabled if ``suppress_silence = True``.
use_word_position : bool, default True
    Whether to use position of the word in its segment to determine whether to keep end or start timestamps if
    adjustments are required. If it is the first word, keep end. Else if it is the last word, keep the start.
q_levels : int, default 20
    Quantization levels for generating timestamp suppression mask; ignored if ``vad = true``.
    Acts as a threshold to marking sound as silent.
    Fewer levels will increase the threshold of volume at which to mark a sound as silent.
k_size : int, default 5
    Kernel size for avg-pooling waveform to generate timestamp suppression mask; ignored if ``vad = true``.
    Recommend 5 or 3; higher sizes will reduce detection of silence.
denoiser : str, optional
    String of the denoiser to use for preprocessing ``audio``.
    See ``stable_whisper.audio.SUPPORTED_DENOISERS`` for supported denoisers.
denoiser_options : dict, optional
    Options to use for ``denoiser``.
vad : bool or dict, default False
    Whether to use Silero VAD to generate timestamp suppression mask.
    Instead of ``True``, using a dict of keyword arguments will load the VAD with the arguments.
    Silero VAD requires PyTorch 1.12.0+. Official repo, https://github.com/snakers4/silero-vad.
vad_threshold : float, default 0.35
    Threshold for detecting speech with Silero VAD. Low threshold reduces false positives for silence detection.
min_word_dur : float or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Shortest duration each word is allowed to reach for silence suppression.
min_silence_dur : float, optional
    Shortest duration of silence allowed for silence suppression.
nonspeech_error : float, default 0.1
    Relative error of non-speech sections that appear in between a word for silence suppression.
only_voice_freq : bool, default False
    Whether to only use sound between 200 - 5000 Hz, where majority of human speech are.
prepend_punctuations : str or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Punctuations to prepend to next word.
append_punctuations : str or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Punctuations to append to previous word.
progress_callback : Callable, optional
    A function that will be called when transcription progress is updated.
    The callback need two parameters.
    The first parameter is a float for seconds of the audio that has been transcribed.
    The second parameter is a float for total duration of audio in seconds.
ignore_compatibility : bool, default False
    Whether to ignore warnings for compatibility issues with the detected Whisper version.
extra_models : list of whisper.model.Whisper, optional
    List of additional Whisper model instances to use for computing word-timestamps along with ``model``.
presplit : bool or list of str, default True meaning same as ``append_punctuations``
    List of ending punctuation used to split ``text`` into segments for applying ``gap_padding``,
    but segmentation of final output is unnaffected unless ``original_split=True``.
    If ``original_split=True``, the original split is used instead of split from ``presplit``.
    Ignored if ``model`` is a faster-whisper model.
gap_padding : str, default ' ...'
    Only if ``presplit=True``, ``gap_padding`` is prepended to each segments for word timing alignment.
    Used to reduce the probability of model predicting timestamps earlier than the first utterance.
    Ignored if ``model`` is a faster-whisper model.
dynamic_heads : bool or int or str, optional
    Whether to find optimal cross-attention heads during runtime instead of using the predefined heads for 
    word-timestamp extraction. Specify the number of heads or `True` for default of 6 heads.
    To specify number of iterations for finding the optimal heads,
    use string with "," to separate heads and iterations (e.g. "8,3" for 8 heads and 3 iterations).

Returns
-------
stable_whisper.result.WhisperResult or None
    All timestamps, words, probabilities, and other data from the alignment of ``audio``. Return None if alignment
    fails and ``remove_instant_words = True``.

Notes
-----
If ``token_step`` is less than 1, ``token_step`` will be set to its maximum value, 442. This value is computed with
``whisper.model.Whisper.dims.n_text_ctx`` - 6.

IF ``original_split = True`` and a line break is found in middle of a word in ``text``, the split will occur after
that word.

``regroup`` is ignored if ``original_split = True``.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.align('helloworld.mp3', 'Hello, World!', 'English')
>>> result.to_srt_vtt('helloword.srt')
Saved 'helloworld.srt'

Align segments of plain text or tokens with audio at word-level at specified start and end of each segment.

This is a version of ``align()`` that confines each segment to a range of timestamps which eliminates the need
for the fallback mechanisms used in ``align()``. This makes this method draticastilly faster than ``align()`` and
reduces word-timstamp errors if the provided start and end timestamps of each segment is accurate.

Parameters
----------
model : "Whisper"
    The Whisper ASR model modified instance
audio : str or numpy.ndarray or torch.Tensor or bytes or AudioLoader
    Path/URL to the audio file, the audio waveform, or bytes of audio file or
    instance of :class:`stable_whisper.audio.AudioLoader`.
    If audio is :class:`numpy.ndarray` or :class:`torch.Tensor`, the audio must be already at sampled to 16kHz.
result : stable_whisper.result.WhisperResult or list of dict
    Instance of :class:`stable_whisper.result.WhisperResult` or List of dictionaries with start, end, and text.
language : str, default None, uses ``language`` in ``text`` if it is a :class:`stable_whisper.result.WhisperResult`
    Language of ``text``. Required if ``text`` does not contain ``language``.
tokenizer : "Tokenizer", default None, meaning a new tokenizer is created according ``language`` and ``model``
    A tokenizer to used tokenizer text and detokenize tokens.
stream : bool or None, default None
    Whether to loading ``audio`` in chunks of 30 seconds until the end of file/stream.
    If ``None`` and ``audio`` is a string then set to ``True`` else ``False``.
verbose : bool or None, default False
    Whether to display the text being decoded to the console.
    Displays all the details if ``True``. Displays progressbar if ``False``. Display nothing if ``None``.
regroup : bool or str, default True, meaning the default regroup algorithm
    String for customizing the regrouping algorithm. False disables regrouping.
    Ignored if ``word_timestamps = False``.
suppress_silence : bool, default True
    Whether to enable timestamps adjustments based on the detected silence.
suppress_word_ts : bool, default True
    Whether to adjust word timestamps based on the detected silence. Only enabled if ``suppress_silence = True``.
use_word_position : bool, default True
    Whether to use position of the word in its segment to determine whether to keep end or start timestamps if
    adjustments are required. If it is the first word, keep end. Else if it is the last word, keep the start.
q_levels : int, default 20
    Quantization levels for generating timestamp suppression mask; ignored if ``vad = true``.
    Acts as a threshold to marking sound as silent.
    Fewer levels will increase the threshold of volume at which to mark a sound as silent.
k_size : int, default 5
    Kernel size for avg-pooling waveform to generate timestamp suppression mask; ignored if ``vad = true``.
    Recommend 5 or 3; higher sizes will reduce detection of silence.
denoiser : str, optional
    String of the denoiser to use for preprocessing ``audio``.
    See ``stable_whisper.audio.SUPPORTED_DENOISERS`` for supported denoisers.
denoiser_options : dict, optional
    Options to use for ``denoiser``.
vad : bool or dict, default False
    Whether to use Silero VAD to generate timestamp suppression mask.
    Instead of ``True``, using a dict of keyword arguments will load the VAD with the arguments.
    Silero VAD requires PyTorch 1.12.0+. Official repo, https://github.com/snakers4/silero-vad.
vad_threshold : float, default 0.35
    Threshold for detecting speech with Silero VAD. Low threshold reduces false positives for silence detection.
min_word_dur : float or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Shortest duration each word is allowed to reach for silence suppression.
min_silence_dur : float, optional
    Shortest duration of silence allowed for silence suppression.
nonspeech_error : float, default 0.1
    Relative error of non-speech sections that appear in between a word for silence suppression.
only_voice_freq : bool, default False
    Whether to only use sound between 200 - 5000 Hz, where majority of human speech are.
prepend_punctuations : str or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Punctuations to prepend to next word.
append_punctuations : str or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
    Punctuations to append to previous word.
progress_callback : Callable, optional
    A function that will be called when transcription progress is updated.
    The callback need two parameters.
    The first parameter is a float for seconds of the audio that has been transcribed.
    The second parameter is a float for total duration of audio in seconds.
ignore_compatibility : bool, default False
    Whether to ignore warnings for compatibility issues with the detected Whisper version.
extra_models : list of whisper.model.Whisper, optional
    List of additional Whisper model instances to use for computing word-timestamps along with ``model``.
presplit : bool or list of str, default True meaning same as ``append_punctuations``
    List of ending punctuation used to split ``text`` into segments for applying ``gap_padding``,
    but segmentation of final output is unnaffected unless ``original_split=True``.
    If ``original_split=True``, the original split is used instead of split from ``presplit``.
    Ignored if ``model`` is a faster-whisper model.
gap_padding : str, default ' ...'
    Only if ``presplit=True``, ``gap_padding`` is prepended to each segments for word timing alignment.
    Used to reduce the probability of model predicting timestamps earlier than the first utterance.
    Ignored if ``model`` is a faster-whisper model.
dynamic_heads : bool or int or str, optional
    Whether to find optimal cross-attention heads during runtime instead of using the predefined heads for
    word-timestamp extraction. Specify the number of heads or `True` for default of 6 heads.
    To specify number of iterations for finding the optimal heads,
    use string with "," to separate heads and iterations (e.g. "8,3" for 8 heads and 3 iterations).
normalize_text : bool or dict, default True
    Whether to normalize text of each segment.
inplace : bool, default True
    Whether to add word-timestamps to ``result`` if it is instance of :class:`stable_whisper.result.WhisperResult`.

Returns
-------
stable_whisper.result.WhisperResult
    All timestamps, words, probabilities, and other data from the alignment of ``audio``.
    Same object as ``result`` if ``inplace=True`` (default) and ``result`` is a ``WhisperResult``.

    Minimize the duration of words using timestamps of another result.
    
    Parameters
    ----------
    other_result : "WhisperResult"
        Timing data of the same words in a WhisperResult instance.
    min_word_dur : float or None, default None meaning use ``stable_whisper.default.DEFAULT_VALUES``
        Prevent changes to timestamps if the resultant word duration is less than ``min_word_dur``.
    verbose : bool, default False
        Whether to print out the timestamp changes.

stable-ts audio.mp3 --refine -o audio.srt

Input can also be JSON file of a result.

stable-ts result.json --refine -o audio.srt --refine_option "audio=audio.mp3"

Improve existing timestamps.

This function iteratively muting portions of the audio and monitoring token probabilities to find the most precise
timestamps. This "most precise" in this case means the latest start and earliest end of a word that maintains an
acceptable probability determined by the specified arguments.

This is useful readjusting timestamps when they start too early or end too late.

Parameters
----------
model : "Whisper"
    The Whisper ASR model modified instance
audio : str or numpy.ndarray or torch.Tensor or bytes
    Path/URL to the audio file, the audio waveform, or bytes of audio file.
    If audio is :class:`numpy.ndarray` or :class:`torch.Tensor`, the audio must be already at sampled to 16kHz.
result : stable_whisper.result.WhisperResult
    All timestamps, words, probabilities, and other data from the transcription of ``audio``.
steps : str, default 'se'
    Instructions for refinement. A 's' means refine start-timestamps. An 'e' means refine end-timestamps.
rel_prob_decrease : float, default 0.3
    Maximum percent decrease in probability relative to original probability which is the probability from muting
    according initial timestamps.
abs_prob_decrease : float, default 0.05
    Maximum decrease in probability from original probability.
rel_rel_prob_decrease : float, optional
    Maximum percent decrease in probability relative to previous probability which is the probability from previous
    iteration of muting.
prob_threshold : float, default 0.5
    Stop refining the timestamp if the probability of its token goes below this value.
rel_dur_change : float, default 0.5
    Maximum percent change in duration of a word relative to its original duration.
abs_dur_change : float, optional
    Maximum seconds a word is allowed deviate from its original duration.
word_level : bool, default True
    Whether to refine timestamps on word-level. If ``False``, only refine start/end timestamps of each segment.
precision : float, default 0.1
    Precision of refined timestamps in seconds. The lowest precision is 0.02 second.
single_batch : bool, default False
    Whether to process in only batch size of one to reduce memory usage.
inplace : bool, default True
    Whether to alter timestamps in-place. Return a deepcopy of ``result`` if ``False``.
denoiser : str, optional
    String of the denoiser to use for preprocessing ``audio``.
    See ``stable_whisper.audio.SUPPORTED_DENOISERS`` for supported denoisers.
denoiser_options : dict, optional
    Options to use for ``denoiser``.
only_voice_freq : bool, default False
    Whether to only use sound between 200 - 5000 Hz, where majority of human speech are.
verbose : bool or None, default False
    Whether to display the text being decoded to the console.
    Displays all the details if ``True``. Displays progressbar if ``False``. Display nothing if ``None``.

Returns
-------
stable_whisper.result.WhisperResult
    All timestamps, words, probabilities, and other data from the refinement of ``text`` with ``audio``.

Notes
-----
The lower the ``precision``, the longer the processing time.

Faster-Whisper models are significantly slower than vanilla models with this function.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> result = model.transcribe('audio.mp3')
>>> model.refine('audio.mp3', result)
>>> result.to_srt_vtt('audio.srt')
Saved 'audio.srt'

    Regroup (in-place) words into segments.

    Parameters
    ----------
    regroup_algo: str or bool, default 'da'
         String representation of a custom regrouping algorithm or ``True`` use to the default algorithm 'da'.
    verbose : bool, default False
        Whether to show all the methods and arguments parsed from ``regroup_algo``.
    only_show : bool, default False
        Whether to show the all methods and arguments parsed from ``regroup_algo`` without running the methods

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Notes
    -----
    Syntax for string representation of custom regrouping algorithm.
        Method keys:
            sg: split_by_gap
            sp: split_by_punctuation
            sl: split_by_length
            sd: split_by_duration
            mg: merge_by_gap
            mp: merge_by_punctuation
            ms: merge_all_segment
            cm: clamp_max
            l: lock
            us: unlock_all_segments
            da: default algorithm (isp_cm_sp=.* /。/?/？_sg=.5_sp=,* /，++++50_sl=70_cm)
            rw: remove_word
            rs: remove_segment
            rp: remove_repetition
            rws: remove_words_by_str
            fg: fill_in_gaps
            p: pad
            ag: adjust_gaps
            csl: convert_to_segment_level
            co: custom_operation
            isp: ignore_special_periods
        Metacharacters:
            = separates a method key and its arguments (not used if no argument)
            _ separates method keys (after arguments if there are any)
            + separates arguments for a method key
            / separates an argument into list of strings
            * separates an item in list of strings into a nested list of strings
        Notes:
        -arguments are parsed positionally
        -if no argument is provided, the default ones will be used
        -use 1 or 0 to represent True or False
        -use a space to in place of _ for ``key`` of ``custom_operation`` to avoid conflict with the metacharacter
        -use strings "" or "" to represent True or False for ``value`` of ``custom_operation``
        Example 1:
            merge_by_gap(.2, 10, lock=True)
            mg=.2+10+++1
            Note: [lock] is the 5th argument hence the 2 missing arguments inbetween the three + before 1
        Example 2:
            split_by_punctuation([('.', ' '), '。', '?', '？'], True)
            sp=.* /。/?/？+1
        Example 3:
            merge_all_segments().split_by_gap(.5).merge_by_gap(.15, 3)
            ms_sg=.5_mg=.15+3
        Examples 4:
            custom_operation('compression_ratio', '>', 3.0, 'remove', word_level=False)
            co=compression ratio+>+3.0+remove+0

    Split (in-place) any segment where the gap between two of its words is greater than ``max_gap``.

    Parameters
    ----------
    max_gap : float, default 0.1
        Maximum second(s) allowed between two words if the same segment.
    lock : bool, default False
        Whether to prevent future splits/merges from altering changes made by this method.
    newline: bool, default False
        Whether to insert line break at the split points instead of splitting into separate segments.
    ignore_special_periods : bool, default False
        Whether to avoid splitting at periods that is likely not an indication of the end of a sentence.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Split (in-place) segments at words that start/end with ``punctuation``.

    Parameters
    ----------
    punctuation : list of str or list of tuple of (str, str) or str
        Punctuation(s) to split segments by.
    lock : bool, default False
        Whether to prevent future splits/merges from altering changes made by this method.
    newline : bool, default False
        Whether to insert line break at the split points instead of splitting into separate segments.
    min_words : int, optional
        Split segments with words >= ``min_words``.
    min_chars : int, optional
        Split segments with characters >= ``min_chars``.
    min_dur : int, optional
        split segments with duration (in seconds) >= ``min_dur``.
    ignore_special_periods : bool, default False
        Whether to avoid splitting at periods that is likely not an indication of the end of a sentence.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Split (in-place) any segment that exceeds ``max_chars`` or ``max_words`` into smaller segments.

    Parameters
    ----------
    max_chars : int, optional
        Maximum number of characters allowed in each segment.
    max_words : int, optional
        Maximum number of words allowed in each segment.
    even_split : bool, default True
        Whether to evenly split a segment in length if it exceeds ``max_chars`` or ``max_words``.
    force_len : bool, default False
        Whether to force a constant length for each segment except the last segment.
        This will ignore all previous non-locked segment boundaries.
    lock : bool, default False
        Whether to prevent future splits/merges from altering changes made by this method.
    include_lock: bool, default False
        Whether to include previous lock before splitting based on max_words, if ``even_split = False``.
        Splitting will be done after the first non-locked word > ``max_chars`` / ``max_words``.
    newline: bool, default False
        Whether to insert line break at the split points instead of splitting into separate segments.
    ignore_special_periods : bool, default False
        Whether to avoid splitting at periods that is likely not an indication of the end of a sentence.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Notes
    -----
    If ``even_split = True``, segments can still exceed ``max_chars``.
    uneven splitting.

    Split (in-place) any segment that exceeds ``max_dur`` into smaller segments.

    Parameters
    ----------
    max_dur : float
        Maximum duration (in seconds) per segment.
    even_split : bool, default True
        Whether to evenly split a segment in length if it exceeds ``max_dur``.
    force_len : bool, default False
        Whether to force a constant length for each segment except the last segment.
        This will ignore all previous non-locked segment boundaries.
    lock : bool, default False
        Whether to prevent future splits/merges from altering changes made by this method.
    include_lock: bool, default False
        Whether to include previous lock before splitting based on max_words, if ``even_split = False``.
        Splitting will be done after the first non-locked word > ``max_dur``.
    newline: bool, default False
        Whether to insert line break at the split points instead of splitting into separate segments.
    ignore_special_periods : bool, default False
        Whether to avoid splitting at periods that is likely not an indication of the end of a sentence.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Notes
    -----
    If ``even_split = True``, segments can still exceed ``max_dur``.
    uneven splitting.

    Merge (in-place) any pair of adjacent segments if the gap between them <= ``min_gap``.

    Parameters
    ----------
    min_gap : float, default 0.1
        Minimum second(s) allow between two segment.
    max_words : int, optional
        Maximum number of words allowed in each segment.
    max_chars : int, optional
        Maximum number of characters allowed in each segment.
    is_sum_max : bool, default False
        Whether ``max_words`` and ``max_chars`` is applied to the merged segment instead of the individual segments
        to be merged.
    lock : bool, default False
        Whether to prevent future splits/merges from altering changes made by this method.
    newline : bool, default False
        Whether to insert a line break between the merged segments.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Merge (in-place) any two segments that has specific punctuations inbetween.

    Parameters
    ----------
    punctuation : list of str or list of tuple of (str, str) or str
        Punctuation(s) to merge segments by.
    max_words : int, optional
        Maximum number of words allowed in each segment.
    max_chars : int, optional
        Maximum number of characters allowed in each segment.
    is_sum_max : bool, default False
        Whether ``max_words`` and ``max_chars`` is applied to the merged segment instead of the individual segments
        to be merged.
    lock : bool, default False
        Whether to prevent future splits/merges from altering changes made by this method.
    newline : bool, default False
        Whether to insert a line break between the merged segments.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Merge all segments into one segment.

    Parameters
    ----------
    record : bool , default True
        Whether to record this operation in ``regroup_history``.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Clamp all word durations above certain value.

    This is most effective when applied before and after other regroup operations.

    Parameters
    ----------
    medium_factor : float, default 2.5
        Clamp durations above (``medium_factor`` * medium duration) per segment.
        If ``medium_factor = None/0`` or segment has less than 2 words, it will be ignored and use only ``max_dur``.
    max_dur : float, optional
        Clamp durations above ``max_dur``.
    clip_start : bool or None, default None
        Whether to clamp the start of a word. If ``None``, clamp the start of first word and end of last word per
        segment.
    verbose : bool, default False
        Whether to print out the timestamp changes.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Lock words/segments with matching prefix/suffix to prevent splitting/merging.

    Parameters
    ----------
    startswith: str or list of str
        Prefixes to lock.
    endswith: str or list of str
        Suffixes to lock.
    right : bool, default True
        Whether prevent splits/merges with the next word/segment.
    left : bool, default False
        Whether prevent splits/merges with the previous word/segment.
    case_sensitive : bool, default False
        Whether to match the case of the prefixes/suffixes with the words/segments.
    strip : bool, default True
        Whether to ignore spaces before and after both words/segments and prefixes/suffixes.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Pad (in-place) timestamps in chronological order.

    Parameters
    ----------
    start_pad : float, optional
        Seconds to pad start timestamps.
        Each start timestamp will be extended no earlier than the end timestamp of the previous word.
    end_pad : float, optional
        Seconds to pad end timestamps.
        Each end timestamp will be extended no later than the start timestamp of the next word or ``max_end``.
    max_dur : float, optional
        Only pad segments or words (``word_level=True``) with duration (in seconds) under or equal to ``max_dur``.
    max_end : float, optional
        Timestamp (in seconds) that padded timestamps cannot exceed.
        Generally used to prevent the last padded end timestamp from exceeding the total duration of the audio.
    word_level : bool, default False
        Whether to pad segment timestamps or word timestamps.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Set ``enable`` as default for ``ignore_special_periods`` in all methods with ``ignore_special_periods``.

    Parameters
    ----------
    enable : bool, default True
        Value to set ``ignore_special_periods`` for methods that has this option.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Perform custom operation on words/segments that satisfy specified conditions.

    Parameters
    ----------
    key : str
        Attribute of words/segments to get value for comparing with ``value``.
        If ``key`` is empty string, directly use the instance of ``WordTiming``/``Segment`` object for comparison.
        All " " in ``key`` will be replaced with "_".
        Start with "len=" to get length of the attribute.
    operator : str or Callable
        Operator or function for comparing vaLue of ``key`` and ``value``.
        Built-in operators: ==, >, >=, <, <=, is, in, start, end
        Function must return a boolean and accept two arguments: vaLue of ``key``, ``value``.
    value : any
        Value to compare with vaLue of ``key``.
        To express multiple values as a string:
            -start string with "all=" or "any=" followed with values separated by ','
            -use "\" to escape values with "," in values
            -these values can only be conbination of str, int, float
            -start with "all=": all values are required to meet the condition to be satisfied
            -start with "any=": only require one of the values to meet the conditions to be satified
    method : str or Callable
        Operation or function to check if words/segments meet conditions.
        Built-in operations:
            mergeleft, mergeright, merge, lockright, lockleft, lock, splitright, splitleft, split, remove
        Function must accept three arguments: this instance of `WhisperResult`, segment index, word index.
    word_level : bool, default None, meaning True if this instance has word-timestamps
        Whether to operate on words. Operate on segments if ``False``.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Remove a word.

    Parameters
    ----------
    word : WordTiming or tuple of (int, int)
        Instance of :class:`stable_whisper.result.WordTiming` or tuple of (segment index, word index).
    reassign_ids : bool, default True
        Whether to reassign segment and word ids (indices) after removing ``word``.
    verbose : bool, default True
        Whether to print detail of the removed word.
    record : bool , default True
        Whether to record this operation in ``regroup_history``.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Remove a segment.

    Parameters
    ----------
    segment : Segment or int
        Instance :class:`stable_whisper.result.Segment` or segment index.
    reassign_ids : bool, default True
        Whether to reassign segment IDs (indices) after removing ``segment``.
    verbose : bool, default True
        Whether to print detail of the removed word.
    record : bool , default True
        Whether to record this operation in ``regroup_history``.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Remove words that repeat consecutively.

    Parameters
    ----------
    max_words : int
        Maximum number of words to look for consecutively.
    case_sensitive : bool, default False
        Whether the case of words need to match to be considered as repetition.
    strip : bool, default True
        Whether to ignore spaces before and after each word.
    ignore_punctuations : bool, default '"',.?!'
        Ending punctuations to ignore.
    extend_duration: bool, default True
        Whether to extend the duration of the previous word to cover the duration of the repetition.
    verbose: bool, default True
        Whether to print detail of the removed repetitions.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Remove words that match ``words``.

    Parameters
    ----------
    words : str or list of str or None
        A word or list of words to remove.``None`` for all words to be passed into ``filters``.
    case_sensitive : bool, default False
        Whether the case of words need to match to be considered as repetition.
    strip : bool, default True
        Whether to ignore spaces before and after each word.
    ignore_punctuations : bool, default '"',.?!'
        Ending punctuations to ignore.
    min_prob : float, optional
        Acts as the first filter the for the words that match ``words``. Words with probability < ``min_prob`` will
        be removed if ``filters`` is ``None``, else pass the words into ``filters``. Words without probability will
        be treated as having probability < ``min_prob``.
    filters : Callable, optional
        A function that takes an instance of :class:`stable_whisper.result.WordTiming` as its only argument.
        This function is custom filter for the words that match ``words`` and were not caught by ``min_prob``.
    verbose:
        Whether to print detail of the removed words.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Fill in segment gaps larger than ``min_gap`` with content from ``other_result`` at the times of gaps.

    Parameters
    ----------
    other_result : WhisperResult or str
        Another transcription result as an instance of :class:`stable_whisper.result.WhisperResult` or path to the
        JSON of the result.
    min_gap : float, default 0.1
        The minimum seconds of a gap between segments that must be exceeded to be filled in.
    case_sensitive : bool, default False
        Whether to consider the case of the first and last word of the gap to determine overlapping words to remove
        before filling in.
    strip : bool, default True
        Whether to ignore spaces before and after the first and last word of the gap to determine overlapping words
        to remove before filling in.
    ignore_punctuations : bool, default '"',.?!'
        Ending punctuations to ignore in the first and last word of the gap to determine overlapping words to
        remove before filling in.
    verbose:
        Whether to print detail of the filled content.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

Locate when specific words are spoken in ``audio`` without fully transcribing.

This is usefully for quickly finding at what time the specify words or phrases are spoken in an audio. Since it
does not need to transcribe the audio to approximate the time, it is significantly faster transcribing then
locating the word in the transcript.

It can also transcribe few seconds around the approximated time to find out what was said around those words or
confirm if the word was even spoken near that time.

Parameters
----------
model : whisper.model.Whisper
    An instance of Whisper ASR model.
audio : str or numpy.ndarray or torch.Tensor or bytes
    Path/URL to the audio file, the audio waveform, or bytes of audio file.
    If audio is :class:`numpy.ndarray` or :class:`torch.Tensor`, the audio must be already at sampled to 16kHz.
text: str or list of int
    Words/phrase or list of tokens to search for in ``audio``.
language : str
    Language of the ``text``.
count : int, default 1, meaning stop search after 1 match
    Number of matches to find. Use 0 to look for all.
duration_window : float or tuple of (float, float), default 3.0, same as (3.0, 3.0)
    Seconds before and after the end timestamp approximations to transcribe after mode 1.
    If tuple pair of values, then the 1st value will be seconds before the end and 2nd value will be seconds after.
mode : int, default 0
    Mode of search.
    2, Approximates the end timestamp of ``text`` in the audio. This mode does not confirm whether ``text`` is
        spoken at the timestamp
    1, Completes mode 2 then transcribes audio within ``duration_window`` to confirm whether `text` is a match at
        the approximated timestamp by checking if ``text`` at that ``duration_window`` is within
        ``probability_threshold`` or matching the string content if ``text`` with the transcribed text at the
        ``duration_window``.
    0, Completes mode 1 then add word timestamps to the transcriptions of each match.
    Modes from fastest to slowest: 2, 1, 0
start : float, optional, meaning it starts from 0s
    Seconds into the audio to start searching for ``text``.
end : float, optional
    Seconds into the audio to stop searching for ``text``.
probability_threshold : float, default 0.5
    Minimum probability of each token in ``text`` for it to be considered a match.
eots : int, default 1
    Number of EOTs to reach before stopping transcription at mode 1. When transcription reach a EOT, it usually
    means the end of the segment or audio. Once ``text`` is found in the ``duration_window``, the transcription
    will stop immediately upon reaching a EOT.
max_token_per_seg : int, default 20
    Maximum number of tokens to transcribe in the ``duration_window`` before stopping.
exact_token : bool, default False
    Whether to find a match base on the exact tokens that make up ``text``.
case_sensitive : bool, default False
    Whether to consider the case of ``text`` when matching in string content.
verbose : bool or None, default False
    Whether to display the text being decoded to the console.
    Displays all the details if ``True``. Displays progressbar if ``False``. Display nothing if ``None``.
initial_prompt : str, optional
    Text to provide as a prompt for the first window. This can be used to provide, or
    "prompt-engineer" a context for transcription, e.g. custom vocabularies or proper nouns
    to make it more likely to predict those word correctly.
suppress_tokens : str or list of int, default '-1', meaning suppress special characters except common punctuations
    List of tokens to suppress.
denoiser : str, optional
    String of the denoiser to use for preprocessing ``audio``.
    See ``stable_whisper.audio.SUPPORTED_DENOISERS`` for supported denoisers.
denoiser_options : dict, optional
    Options to use for ``denoiser``.
only_voice_freq : bool, default False
    Whether to only use sound between 200 - 5000 Hz, where majority of human speech are.

Returns
-------
stable_whisper.result.Segment or list of dict or list of float
    Mode 0, list of instances of :class:`stable_whisper.result.Segment`.
    Mode 1, list of dictionaries with end timestamp approximation of matches and transcribed neighboring words.
    Mode 2, list of timestamps in seconds for each end timestamp approximation.

Notes
-----
For ``text``, the case and spacing matters as 'on', ' on', ' On' are different tokens, therefore chose the one that
best suits the context (e.g. ' On' to look for it at the beginning of a sentence).

Use a sufficiently large first value of ``duration_window`` i.e. the value > time it is expected to speak ``text``.

If ``exact_token = False`` and the string content matches, then ``probability_threshold`` is not used.

Examples
--------
>>> import stable_whisper
>>> model = stable_whisper.load_model('base')
>>> matches = model.locate('audio.mp3', 'are', language='English', verbose=True)

Some words can sound the same but have different spellings to increase of the chance of finding such words use
``initial_prompt``.

>>> matches = model.locate('audio.mp3', ' Nickie', 'English', verbose=True, initial_prompt='Nickie')

stable-ts audio.mp3 --locate "are" --language en -to "count=0"

    Find segments/words and timestamps with regular expression.

    Parameters
    ----------
    pattern : str
        RegEx pattern to search for.
    word_level : bool, default True
        Whether to search at word-level.
    flags : optional
        RegEx flags.

    Returns
    -------
    stable_whisper.result.WhisperResultMatches
        An instance of :class:`stable_whisper.result.WhisperResultMatches` with word/segment that match ``pattern``.

    Set segment timestamps to the timestamps of overlapping``nonspeech_sections`` within ``duration_threshold``.

    For results with segments split by gaps or punctuations that indicate pauses in speech, the timestamps of these
    gaps are replaced with those in ``nonspeech_sections`` which overlap. These timestamps tend to be more accurate
    if not exact timestamps of the start and end of utterances, especially for audio with no sounds in the gaps.

    Parameters
    ----------
    duration_threshold : float, default 0.75
        Only ``nonspeech_sections`` with duration >= ``duration_threshold`` * duration of the longest section that
        overlaps the existing gap between segments are considered for that gap.
    one_section : bool, default False
        Whether to use only one section of ``nonspeech_sections`` for each gap between segments.
        Recommend ``True`` when there are no sounds in the gaps.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Notes
    -----
    The reliability of this approach hinges on the accuracy of the ``nonspeech_sections`` which is computed when
    ``vad`` is ``False`` or ``True`` for transcription and alignment. The accuracy increases with cleaner audio.
    Results produced by ``vad=True`` will work better with less clean audio (i.e. audio with non-speech sounds).

    Remove all word-level data.

    Converting from word-level to segment-level is useful when the word-level data restricts certain operations that
    need to be performed at the segment-level or when the segment-level results of operations are more desirable.

    Returns
    -------
    stable_whisper.result.WhisperResult
        The current instance after the changes.

    Notes
    -----
    Since many regrouping operations require word-timestamps, it is recommended to only use this method after the
    result has been regrouped into its final segments.

Visualize regions on the waveform of ``audio`` detected as silent.

Regions on the waveform colored red are detected as silent.

Parameters
----------
audio : str or numpy.ndarray or torch.Tensor or bytes
    Path/URL to the audio file, the audio waveform, or bytes of audio file.
    If audio is ``numpy.ndarray`` or ``torch.Tensor``, the audio must be already at sampled to 16kHz.
output : str, default None, meaning image will be shown directly via Pillow or opencv-python
    Path to save visualization.
q_levels : int, default 20
    Quantization levels for generating timestamp suppression mask; ignored if ``vad = true``.
    Acts as a threshold to marking sound as silent.
    Fewer levels will increase the threshold of volume at which to mark a sound as silent.
k_size : int, default 5
    Kernel size for avg-pooling waveform to generate timestamp suppression mask; ignored if ``vad = true``.
    Recommend 5 or 3; higher sizes will reduce detection of silence.
vad : bool or dict, default False
    Whether to use Silero VAD to generate timestamp suppression mask.
    Instead of ``True``, using a dict of keyword arguments will load the VAD with the arguments.
    Silero VAD requires PyTorch 1.12.0+. Official repo, https://github.com/snakers4/silero-vad.
vad_threshold : float, default 0.35
    Threshold for detecting speech with Silero VAD. Low threshold reduces false positives for silence detection.
max_width : int, default 1500
    Maximum width of visualization to avoid overly large image from long audio.
    Each unit of pixel is equivalent  to 1 token.  Use -1 to visualize the entire audio track.
height : int, default 200
    Height of visualization.

Encode multiple subtitle files into one video with the subtitles vertically stacked.

Parameters
----------
audiofile : str
    Path of audio file.
subtitle_files : list of str
    List of paths for subtitle file.
output_videopath : str, optional
    Output video path.
labels : list of str, default, None, meaning use ``subtitle_files`` as labels
    List of labels for ``subtitle_files``.
height : int, default 90
    Height for each subtitle section.
width : int, default 720
    Width for each subtitle section.
color : str, default 'black'
    Background color of the video.
fontsize: int, default 70
    Font size for subtitles.
border_color : str, default 'white'
    Border color for separating the sections of subtitle.
label_color : str, default 'white'
    Color of labels.
label_size : int, default 14
    Font size of labels.
fps : int, default 25
    Frame-rate of the video.
video_codec : str, optional
    Video codec opf the video.
audio_codec : str, optional
    Audio codec opf the video.
overwrite : bool, default False
    Whether to overwrite existing video files with the same path as the output video.
only_cmd : bool, default False
    Whether to skip encoding and only return the full command generate from the specified options.
verbose : bool, default True
    Whether to display ffmpeg processing info.

Returns
-------
str or None
    Encoding command as a string if ``only_cmd = True``.