espnet3.contract.kinds.audio.AudioKind

source

class espnet3.contract.kinds.audio.AudioKind

Bases: Kind

audio: an Audio at the model’s rate, with the field’s channels.

Every channel and the sample rate are preserved by default. channels=N validates the channel count. Use first_channel or mean_channels normalizers to explicitly convert multichannel audio to mono.

accepts(value, field)

Accept anything check() would, plus a bare rate-less array.

check() always needs model.sample_rate, which a model-free caller cannot supply, so the default accepts (which calls check with model=None) would reject every value, including an Audio, a path or a (rate, samples) pair that already carries its own rate. This instead accepts any form Audio.coerce() accepts when given a fixed rate, without requiring one: an Audio, a path, a (rate, samples) pair, or a bare array/tensor.

• Parameters:
  • value – The value to test.
  • field – The declaration the value is for.
• Returns:True when value could be audio, False otherwise.

############### Examples

>>> from espnet3.contract import Field
>>> field = Field("speech", "audio")
>>> AudioKind().accepts(np.zeros(16000, dtype=np.float32), field)
True
>>> AudioKind().accepts((16000, np.zeros(16000, dtype=np.float32)), field)
True
>>> AudioKind().accepts(42, field)
False

check(value, field, model, , output)

Coerce what a caller holds, then validate the field’s channel count.

• Parameters:
  • value – What the caller gave, or what the hook returned - a hook’s bare array is taken to be at the model’s rate.
  • field – The declaration; its channels decides the shape.
  • model – For its sample_rate.
  • output – Whether value is a hook’s result.
• Returns: 1-D for one channel, (channels, samples) otherwise.
• Return type: An Audio at the model’s rate
• Raises:TypeError – If value is not audio, carries no rate when the model fixes none, or has the wrong number of channels.

############### Examples

>>> kind, stereo_in = AudioKind(), (16000, stereo)
>>> mono_field = Field("speech", "audio")
>>> kind.check(stereo_in, mono_field, model, output=False).array.ndim
2
>>> any_channels = Field("mix", "audio", channels=None)
>>> kind.check(stereo_in, any_channels, model, output=False).channels
2
>>> two = Field("mix", "audio", channels=2)
>>> kind.check((16000, mono), two, model, output=False)
Traceback (most recent call last):
TypeError: 'mix' given with 1 channel(s), needs 2

check_configured(value, field, model, options, , output)

Apply the field’s rate policy before the standard audio check.

• Parameters:
  • value – Audio in any form Audio.coerce() accepts.
  • field – The declaration the value is for.
  • model – The instance; its sample_rate is the default rate.
  • options – The field’s options: sample_rate and rate_policy.
  • output – Whether the value is a hook’s result.
• Returns: An Audio at the target rate.
• Raises:ValueError – If the policy is reject and the rates differ.

############### Examples

>>> from espnet3.contract import Field
>>> value = (16000, np.zeros(16000, dtype=np.float32))
>>> audio = AudioKind().check_configured(
...     value, Field("speech", "audio"), None,
...     {"sample_rate": 16000}, output=False,
... )
>>> audio.rate
16000

join(first, second)

Concatenate two pieces of audio in time.

• Parameters:
  • first – The audio gathered so far.
  • second – The audio that follows it.
• Returns: The two as one Audio.

############### Examples

>>> piece = Audio(np.zeros(8000, dtype=np.float32), 8000)
>>> AudioKind().join(piece, piece).duration
2.0

normalizers = {'first_channel': <function AudioKind.<lambda>>, 'mean_channels': <function AudioKind.<lambda>>}

option_names = frozenset({'normalize', 'rate_policy', 'sample_rate'})

to_demo_output(value)

Return Audio as (rate, samples), with channels last for Gradio.

• Parameters:value – A checked output; anything but Audio is returned as is.
• Returns: A (rate, samples) pair for an Audio, else value.

############### Examples

>>> audio = Audio(np.zeros((2, 8000), dtype=np.float32), 8000)
>>> rate, samples = AudioKind().to_demo_output(audio)
>>> rate, samples.shape
(8000, (8000, 2))

validate_options(options) → None

Validate the target sample rate and mismatch policy.

• Parameters:options – The field’s options: sample_rate, rate_policy and normalize.
• Returns: None.
• Raises:ValueError – If sample_rate is not a positive integer or rate_policy is not resample or reject.

############### Examples

>>> AudioKind().validate_options({"sample_rate": 16000})
>>> AudioKind().validate_options({"rate_policy": "keep"})
Traceback (most recent call last):
ValueError: rate_policy must be 'resample' or 'reject'