daft.functions.audio_metadata#

def audio_metadata(
    file_expr: Expression,
) -> Expression:
    """Get metadata for a audio file.

    Args:
        file_expr (AudioFile Expression): The audio file to get metadata for.

    Returns:
        Expression (Struct Expression): A struct containing the metadata
        of the audio file.

        The struct contains the following fields:
            - sample_rate: int - The sample rate of the audio file
            - channels: int - The number of channels in the audio file
            - frames: int - The number of frames in the audio file
            - format: str - The format of the audio file
            - subtype: str | None - The subtype of the audio file

    Examples:
        >>> import daft
        >>> from daft.functions import audio_file, audio_metadata, resample

        >>> # Discover the audio files (returns a dataframe with ['path', 'size'] columns)
        >>> df = daft.from_glob_path("hf://datasets/Eventual-Inc/sample-files/audio/*.mp3")

        >>> df = (
        ...     df.with_column("file", audio_file(daft.col("path")))
        ...     .with_column("metadata", audio_metadata(daft.col("file")))
        ...     .select("path", "size", "metadata")
        ... )
        >>> df.show(3)  # doctest: +SKIP
        ╭────────────────────────────────┬─────────┬──────────────────────────────────────────────────────────────────────╮
        │ path                           ┆ size    ┆ metadata                                                             │
        │ ---                            ┆ ---     ┆ ---                                                                  │
        │ String                         ┆ Int64   ┆ Struct[sample_rate: Int64, channels: Int64, frames: Float64, format: │
        │                                ┆         ┆ String, subtype: String]                                             │
        ╞════════════════════════════════╪═════════╪══════════════════════════════════════════════════════════════════════╡
        │ hf://datasets/Eventual-Inc/sa… ┆ 822924  ┆ {sample_rate: 16000,                                                 │
        │                                ┆         ┆ channels…                                                            │
        ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
        │ hf://datasets/Eventual-Inc/sa… ┆ 618408  ┆ {sample_rate: 16000,                                                 │
        │                                ┆         ┆ channels…                                                            │
        ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
        │ hf://datasets/Eventual-Inc/sa… ┆ 1190736 ┆ {sample_rate: 16000,                                                 │
        │                                ┆         ┆ channels…                                                            │
        ╰────────────────────────────────┴─────────┴──────────────────────────────────────────────────────────────────────╯
        <BLANKLINE>
        (Showing first 3 rows)
    """
    # Check for required dependencies at expression definition time
    from daft.dependencies import sf

    if not sf.module_available():
        raise ImportError(
            "The 'soundfile' module is required to get audio metadata. "
            "Please install it with: pip install 'daft[audio]'"
        )

    return audio_metadata_fn(file_expr)