load()

audb.load(name, *, version=None, only_metadata=False, bit_depth=None, channels=None, format=None, mixdown=False, sampling_rate=None, attachments=None, tables=None, media=None, removed_media=False, full_path=True, pickle_tables=True, cache_root=None, num_workers=1, timeout=-1, verbose=True)[source]

Load database.

Loads meta and media files of a database to the local cache and returns a audformat.Database object.

By setting bit_depth, channels, format, mixdown, and sampling_rate we can request a specific flavor of the database. In that case media files are automatically converted to the desired properties (see also audb.Flavor).

It is possible to filter meta and media files with the arguments tables and media. Only media files with at least one reference are loaded. I.e. filtering meta files, may also remove media files. Likewise, references to missing media files will be removed, too. I.e. filtering media files, may also remove entries from the meta files.

Parameters

  • name (str) – name of database

  • version (Optional[str]) – version string, latest if None

  • only_metadata (bool) – load only header and tables of database

  • bit_depth (Optional[int]) – bit depth, one of 16, 24, 32

  • channels (Union[int, Sequence[int], None]) – channel selection, see audresample.remix(). Note that media files with too few channels will be first upsampled by repeating the existing channels. E.g. channels=[0, 1] upsamples all mono files to stereo, and channels=[1] returns the second channel of all multi-channel files and all mono files

  • format (Optional[str]) – file format, one of 'flac', 'wav'

  • mixdown (bool) – apply mono mix-down

  • sampling_rate (Optional[int]) – sampling rate in Hz, one of 8000, 16000, 22500, 44100, 48000

  • attachments (Union[str, Sequence[str], None]) – load only attachment files for the attachments matching the regular expression or provided in the list. If set to [] no attachments are loaded

  • tables (Union[str, Sequence[str], None]) – load only tables and misc tables matching the regular expression or provided in the list. Media files not referenced in the selected tables are automatically excluded, too. If set to [] no tables and media files are loaded. Misc tables used in schemes are always loaded

  • media (Union[str, Sequence[str], None]) – load only media files matching the regular expression or provided in the list. Excluded media files are automatically removed from the tables, too. This may result in empty tables. If set to [] no media files are loaded and all tables except misc tables will be empty

  • removed_media (bool) – keep rows that reference removed media

  • full_path (bool) – replace relative with absolute file paths

  • pickle_tables (bool) – if True, tables are cached locally in their original format and as pickle files. This allows for faster loading, when loading from cache

  • cache_root (Optional[str]) – cache folder where databases are stored. If not set audb.default_cache_root() is used

  • num_workers (Optional[int]) – number of parallel jobs or 1 for sequential processing. If None will be set to the number of processors on the machine multiplied by 5

  • timeout (float) – maximum wait time if another thread or process is already accessing the database. If timeout is reached, None is returned. If timeout < 0 the method will block until the database can be accessed

  • verbose (bool) – show debug messages

Return type

Optional[Database]

Returns

database object

Raises

  • ValueError – if attachment, table or media is requested that is not part of the database

  • ValueError – if a non-supported bit_depth, format, or sampling_rate is requested

  • RuntimeError – if a flavor is requested, but the database contains media files, that don’t contain audio, e.g. text files

Examples

>>> db = audb.load(
...     "emodb",
...     version="1.4.1",
...     tables=["emotion", "files"],
...     only_metadata=True,
...     full_path=False,
...     verbose=False,
... )
>>> list(db.tables)
['emotion', 'files']