HFile

A collection of methods designed to streamline input and output operations.

Methods

decode

decode(fpath: string, dtype: HDataType) -> HDecodedAudio source

Decode an audio file, providing its decoded data and the sampling rate.

The samples are normalized to fit in the range of [-1.0, 1.0].

Arguments

  • fpath

The file path as a string.

  • dtype

A float HDataType.

Returns

An HDecodedAudio containing:

  • The decoded audio as a float HArray.

  • The sampling rate as an integer.

Examples

library(harmonium)
fpath = "../../../testfiles/gs-16b-2c-44100hz.flac"
dtype = HDataType$Float32
HFile$decode(fpath, dtype)

decode_stream

decode_stream(fpath: string, frames: integer, dtype: HDataType) -> HDecoderStream source

Creates an HDecoderStream, used as an iterator to stream frames of decoded audio.

Arguments

  • fpath

The file path as a string.

  • frames

Number of frames to decode per iteration.

  • dtype

A float HDataType.

Returns

An HDecoderStream.

Examples

library(harmonium)
fpath = "../../../testfiles/gs-16b-2c-44100hz.flac"
dtype = HDataType$Float32
frames = 1000L
HFile$decode_stream(fpath, frames, dtype)

metadata

metadata(fpath: string, metadata_type: HMetadataType) -> list source

Extract text and visual metadata from a file.

Tags that are part of the container format are preferentially extracted. Additional tags that were found while probing will not be extracted.

The following metadata tagging formats are supported.

  • ID3v1
  • ID3v2
  • ISO/MP4
  • RIFF
  • Vorbis Comment (in OGG & FLAC)

Each TextMetadata will be comprised of a Tag, which contains the following fields:

  • tag_key

    A key string indicating the type, meaning, or purpose of the Tags value. Note: The meaning of key is dependant of the underlying metadata format.

  • tag_std_key

    If the Tag’s key string is commonly associated with a typical type, meaning, or purpose, then if recognized a StandardTagKey will be assigned to this Tag. This is a best effort guess since not all metadata formats have a well defined or specified tag mapping. However, it is recommended that consumers prefer std_key over key, if provided.

    Check [StandardTagKey] for all the variants.

  • tag_value

    The value of the Tag.

Each VisualMetadata will be comprised of the following fields:

  • usage

    The usage and/or content of the Visual. A string version of symphonia_core::meta::StandardVisualKey, which is an enumeration providing standardized keys for common visual dispositions. A demuxer may assign a StandardVisualKey to a Visual if the disposition of the attached visual is known and can be mapped to a standard key. The visual types listed here are derived from, though do not entirely cover, the ID3v2 APIC frame specification.

  • media_type

    The Media Type (MIME Type) used to encode the Visual.

  • dimensions

    The dimensions (width and height) of the Visual, represented in pixels. Note: This value may not be accurate as it comes from metadata, not the embedded graphic itself. Consider it only a hint.

  • bits_per_pixel

    The number of bits-per-pixel (aka bit-depth) of the unencoded image.

  • color_mode

    Indicates how the color of a pixel is encoded in a Visual. Variants:

    • Discrete

      Each pixel in the Visual stores its own color information.

    • Indexed(NonZeroU32)

      Each pixel in the Visual stores an index into a color palette containing the color information. The value stored by this variant indicates the number of colors in the color palette.

  • size

    Size of the image in bytes.

  • tag

    Tag with the following fields:

    • tag_key

      A key string indicating the type, meaning, or purpose of the Tags value. Note: The meaning of key is dependant on the underlying metadata format.

    • tag_std_key

      If the Tag’s key string is commonly associated with a typical type, meaning, or purpose, then if recognized a StandardTagKey will be assigned to this Tag. This is a best effort guess since not all metadata formats have a well defined or specified tag mapping. However, it is recommended that consumers prefer std_key over key, if provided.

      Check [StandardTagKey] for all the variants.

    • tag_value

      The value of the Tag.

Arguments

  • fpath

    The file path as a string.

  • metadata_type

    An HMetadataType.

Returns

A list of metadata. An empty list will be returned if there is no metadata in the file.

Examples

library(harmonium)
fpath = "../../../testfiles/gs-16b-2c-44100hz.mp3"
metadata_type = HMetadataType$Text
HFile$metadata(fpath, metadata_type)

params

params(fpath: string) -> atomicvector source

Get audio parameters from a file.

Note that this avoids loading the contents into memory, and is therefore useful for querying these parameters from long files.

Arguments

  • fpath

The file path as a string.

Returns

A double atomic vector containing, in order:

  • sampling rate in Hz.
  • number of frames.
  • number of channels.
  • duration in seconds.

Examples

library(harmonium)
fpath = "../../../testfiles/gs-16b-2c-44100hz.flac"
HFile$params(fpath)

verify

verify(fpath: string) -> string source

Verify an audio file, if supported by the decoder.

The verification is done after the decoding process is finished.

Arguments

  • fpath

The file path as a string.

Returns

A string.

One of [“passed”, “failed”, “not_supported”].

Examples

library(harmonium)
fpath = "../../../testfiles/gs-16b-2c-44100hz.flac"
HFile$verify(fpath)