Skip to main content
`Ctrl`+`K`

# Item

class beets.library.Item(db: D | None = None, fixed_values: dict[str, Any] | None = None, flex_values: dict[str, Any] | None = None, **kwargs: Any)

  Bases: `LibModel`

  Represent a song or track.

  __init__(db: D | None = None, fixed_values: dict[str, Any] | None = None, flex_values: dict[str, Any] | None = None, **kwargs: Any) → None

    Create a new model instance.

    fixed_values/flex_values are raw values loaded from the database and converted lazily on access. kwargs are normal initial field values.

  Public methods summary

  `add`([lib]) | Add the object to the library database.
  `all_keys`() | Get a list of available keys for objects of this type.
  `any_field_query`(pattern, query_cls) |
  `any_writable_media_field_query`(pattern, ...) |
  `clear`() | Set all key/value pairs to None.
  `clear_dirty`() | Mark all fields as clean (i.e., not needing to be stored to the database).
  `copy`() | Create a copy of the model object.
  `current_mtime`() | Return the current mtime of the file, rounded to the nearest integer.
  `destination`([relative_to_libdir, basedir, ...]) | Return the path in the library directory designated for the item (i.e., where the file ought to be).
  `duplicates_query`(fields) | Return a query for entities with same values in the given fields.
  `evaluate_template`(template[, for_path]) | Evaluate a template (a string or a Template object) using the object's fields.
  `field_query`(field, pattern, query_cls) | Get a FieldQuery for the given field on this model.
  `formatted`([included_keys, for_path]) | Get a mapping containing all values on this object formatted as human-readable unicode strings.
  `from_path`(path) | Create a new item from the media file at the specified path.
  `get`(key[, default, with_album]) | Get the value for a given key or default if it does not exist.
  `get_album`() | Get the Album object that this item belongs to, if any, or None if the item is a singleton or is not associated with a library.
  `get_fresh_from_db`() | Load this object from the database.
  `has_cover_art`() | Check if item has embedded cover art.
  `items`() | Iterate over (key, value) pairs that this object contains.
  `keys`([computed, with_album]) | Get a list of available field names.
  `load`() | Refresh the object's metadata from the library database.
  `move`([operation, basedir, with_album, store]) | Move the item to its designated location within the library directory (provided by destination()).
  `move_file`(dest[, operation]) | Move, copy, link or hardlink the item depending on operation, updating the path value if the move succeeds.
  `read`([read_path]) | Read the metadata from the associated file.
  `remove`([delete, with_album]) | Remove the item.
  `set_parse`(key, string) | Set the object's key to a value represented by a string.
  `store`([fields]) | Save the object's metadata into the library database.
  `try_filesize`() | Get the size of the underlying file in bytes.
  `try_sync`(write, move[, with_album]) | Synchronize the item with the database and, possibly, update its tags on disk and its path (by moving the file).
  `try_write`([path, tags, id3v23]) | Call write() but catch and log FileOperationError exceptions.
  `update`(values) | Set all key/value pairs in the mapping.
  `write`([path, tags, id3v23]) | Write the item's metadata to a media file.

  Methods definition

  duplicates_query(fields: list[str]) → AndQuery

    Return a query for entities with same values in the given fields.

  classmethod from_path(path: str | Path | bytes) → Self

    Create a new item from the media file at the specified path.

  keys(computed: bool = False, with_album: bool = True) → KeysView[str]

    Get a list of available field names.

    with_album controls whether the album’s fields are included.

  get(key: str, default: Any = None, with_album: bool = True) → Any

    Get the value for a given key or default if it does not exist.

    Set with_album to false to skip album fallback.

  update(values: Mapping[str, Any]) → None

    Set all key/value pairs in the mapping.

    If mtime is specified, it is not reset (as it might otherwise be).

  clear() → None

    Set all key/value pairs to None.

  get_album() → Album | None

    Get the Album object that this item belongs to, if any, or None if the item is a singleton or is not associated with a library.

  read(read_path: str | Path | bytes | None = None) → None

    Read the metadata from the associated file.

    If read_path is specified, read metadata from that file instead. Update all the properties in _media_fields from the media file.

    Raise a ReadError if the file could not be read.

  write(path: bytes | None = None, tags: Mapping[str, Any] | None = None, id3v23: bool | None = None) → None

    Write the item’s metadata to a media file.

    All fields in _media_fields are written to disk according to the values on this object.

    path is the path of the mediafile to write the data to. It defaults to the item’s path.

    tags is a dictionary of additional metadata the should be written to the file. (These tags need not be in _media_fields.)

    id3v23 will override the global id3v23 config option if it is set to something other than None.

    Can raise either a ReadError or a WriteError.

  try_write(path: bytes | None = None, tags: Mapping[str, Any] | None = None, id3v23: bool | None = None) → bool

    Call write() but catch and log FileOperationError exceptions.

    Return False an exception was caught and True otherwise.

  try_sync(write: bool, move: bool, with_album: bool = True) → None

    Synchronize the item with the database and, possibly, update its tags on disk and its path (by moving the file).

    write indicates whether to write new tags into the file. Similarly, move controls whether the path should be updated. In the latter case, files are only moved when they are inside their library’s directory (if any).

    Similar to calling `write()`, `move()`, and `store()` (conditionally).

  move_file(dest: bytes, operation: MoveOperation = MoveOperation.MOVE) → None

    Move, copy, link or hardlink the item depending on operation, updating the path value if the move succeeds.

    If a file exists at dest, then it is slightly modified to be unique.

    operation should be an instance of util.MoveOperation.

  current_mtime() → int

    Return the current mtime of the file, rounded to the nearest integer.

  try_filesize() → int

    Get the size of the underlying file in bytes.

    If the file is missing, return 0 (and log a warning).

  has_cover_art() → bool

    Check if item has embedded cover art.

    Return True if images embedded in file, False otherwise. If file unreadable or no images, return False.

  remove(delete: bool = False, with_album: bool = True) → None

    Remove the item.

    If delete, then the associated file is removed from disk.

    If with_album, then the item’s album (if any) is removed if the item was the last in the album.

  move(operation: MoveOperation = MoveOperation.MOVE, basedir: bytes | None = None, with_album: bool = True, store: bool = True) → None

    Move the item to its designated location within the library directory (provided by destination()).

    Subdirectories are created as needed. If the operation succeeds, the item’s path field is updated to reflect the new location.

    Instead of moving the item it can also be copied, linked or hardlinked depending on operation which should be an instance of util.MoveOperation.

    basedir overrides the library base directory for the destination.

    If the item is in an album and with_album is True, the album is given an opportunity to move its art.

    By default, the item is stored to the database if it is in the database, so any dirty fields prior to the move() call will be written as a side effect. If store is False however, the item won’t be stored and it will have to be manually stored after invoking this method.

  destination(relative_to_libdir: bool = False, basedir: bytes | None = None, path_formats: list[PathFormat] | None = None) → bytes

    Return the path in the library directory designated for the item (i.e., where the file ought to be).

    The path is returned as a bytestring. `basedir` can override the library’s base directory for the destination. If `relative_to_libdir` is true, returns just the fragment of the path underneath the library base directory.

  add(lib: Library | None = None) → None

    Add the object to the library database. This object must be associated with a database; you can provide one via the db parameter or use the currently associated database.

    The object’s id and added fields are set along with any current field values.

  classmethod all_keys() → KeysView[str]

    Get a list of available keys for objects of this type. Includes fixed and computed fields.

  clear_dirty() → None

    Mark all fields as clean (i.e., not needing to be stored to the database). Also update the revision.

  copy() → Self

    Create a copy of the model object.

    The field values and other state is duplicated, but the new copy remains associated with the same database as the old object. (A simple copy.deepcopy will not work because it would try to duplicate the SQLite connection.)

  property db: D

    Get the database associated with this object.

    This validates that the database is attached and the object has an id.

  evaluate_template(template: str | Template, for_path: bool = False) → str

    Evaluate a template (a string or a Template object) using the object’s fields. If for_path is true, then no new path separators will be added to the template.

  classmethod field_query(field: str, pattern: str, query_cls: FieldQueryType) → FieldQuery

    Get a FieldQuery for the given field on this model.

  property filepath: Path

    The path to the entity as pathlib.Path.

  formatted(included_keys: str = '*', for_path: bool = False) → FormattedMapping

    Get a mapping containing all values on this object formatted as human-readable unicode strings.

  get_fresh_from_db() → Self

    Load this object from the database.

  items() → Iterator[tuple[str, Any]]

    Iterate over (key, value) pairs that this object contains. Computed fields are not included.

  load() → None

    Refresh the object’s metadata from the library database.

    If check_revision is true, the database is only queried loaded when a transaction has been committed since the item was last loaded.

  set_parse(key: str, string: str) → None

    Set the object’s key to a value represented by a string.

  store(fields: Iterable[str] | None = None) → None

    Save the object’s metadata into the library database. :param fields: the fields to be stored. If not specified, all fields will be.