<commit_before># NAME

Audio::Taglib::Simple - Read, write ID3 and other audio metadata with TagLib

# SYNOPSIS

```perl6
my $taglib = Audio::Taglib::Simple.new("awesome.mp3");
say "artist: ", $taglib.artist;

$taglib.set-artist("Awesome Band");
$taglib.save()
```

See also examples/taglib.p6

# DESCRIPTION

This module uses NativeCall to provide bindings to TagLib's C API. The C API is
the "simple" API, which only provides commonly used fields that are abstracted
over all file types.

TagLib supports many audio and tag formats. Audio formats include MP3, MPC,
FLAC, MP4, ASF, AIFF, WAV, TrueAudio, WavPack, Ogg FLAC, Ogg Vorbis, Speex and
Opus file formats. Tag formats include ID3v1, ID3v2, APE, FLAC, Xiph,
iTunes-style MP4 and WMA. See their website for an exhaustive list.

TagLib is nice and fast. The example script runs on a directory of 501 files
(499 are MP3, 2 are non-audio) in around 4 seconds.

All of the API methods are read only. Modifying a file is not yet supported.

# METHODS

## new($file)

Prepares to read the provided file. Dies if the file does not exist or if
TagLib cannot parse it. TagLib attempts to guess the file type here.

## file

Readonly accessor to the file variable passed in.

## artist

## album

## title

## comment

## genre

## year

Returns the year associated with the song as an integer (e.g. 2004) or 0 if not
present.

## track

Returns the track number of this song as an integer (e.g. 12) or 0 if not
present.

## length

Returns the length of the file as a Duration. TagLib provides it as an integer.

## bitrate

Returns the bit rate of the file as an Int in kb/s. Example: 128.

## samplerate

Returns the sample rate of the file as an Int in Hz. Example: 44100.

## channels

Returns the number of channels present in the file as an Int. Example: 2.

## set-artist(Str)

## set-album(Str)

## set-title(Str)

## set-comment(Str)

## set-genre(Str)

## set-year(Int)

## save() returns Bool

Call save after one or more set-foo mutators to write out the changes.

# CAVEATS

- TagLib prints some warnings to STDERR directly.
- All fields are read from the metadata, and corrupted files can often have
  incorrect values for length. TagLib does not actually parse the music stream
  to find this out.
- Tags are read at object initialization time. This means that if some other
  process modifies the tags on the music file, you won't see changes unless you
  create a new object.
<commit_msg>Bring README in line with reality<commit_after># NAME

Audio::Taglib::Simple - Read, write ID3 and other audio metadata with TagLib

# SYNOPSIS

```perl6
my $taglib = Audio::Taglib::Simple.new("awesome.mp3");

# read a tag
say "artist: ", $taglib.artist;

# edit a tag
$taglib.artist = "Awesome Band";
$taglib.save()
```

See also examples/taglib.p6

# DESCRIPTION

This module uses NativeCall to provide bindings to TagLib's C API. The C API is
the "simple" API, which only provides commonly used fields that are abstracted
over all file types.

TagLib supports many audio and tag formats. Audio formats include MP3, MPC,
FLAC, MP4, ASF, AIFF, WAV, TrueAudio, WavPack, Ogg FLAC, Ogg Vorbis, Speex and
Opus file formats. Tag formats include ID3v1, ID3v2, APE, FLAC, Xiph,
iTunes-style MP4 and WMA. See their website for an exhaustive list.

TagLib is nice and fast. The example script runs on a directory of 501 files
(499 are MP3, 2 are non-audio) in around 4 seconds.

All of the API methods are read only. Modifying a file is not yet supported.

# METHODS

## new($file)

Prepares to read the provided file. Dies if the file does not exist or if
TagLib cannot parse it. TagLib attempts to guess the file type here.

## file

Readonly accessor to the file variable passed in.

## artist() returns Str

Returns the artist of the song.

## album() returns Str

Returns the name of the album associated with the song.

## title() returns Str

Returns the title of the song.

## comment() returns Str

A generic comment field.

## genre() returns Str

A string describing the genre.

## year() returns Int

Returns the year associated with the song as an integer (e.g. 2004) or 0 if not
present.

## track() returns Int

Returns the track number of this song as an integer (e.g. 12) or 0 if not
present.

## save() returns Bool

Call save after assigning to one or more tag attributes (listed above) to write
out the changes.

## length() returns Duration

Returns the length of the file as a Duration. TagLib provides it as an integer.
Not editable.

## bitrate() returns Int

Returns the bit rate of the file as an Int in kb/s. Example: 128. Not editable.

## samplerate() returns Int

Returns the sample rate of the file as an Int in Hz. Example: 44100. Not
editable.

## channels() returns Int

Returns the number of channels present in the file as an Int. Example: 2. Not
editable.

# EXCEPTIONS

## X::InvalidAudioFile

The constructor may raise exceptions if the file does not exist or does not
appear to be audio that TagLib can parse.

### file

The file that is invalid.

### text

The specific error text.

# CAVEATS

- TagLib prints some warnings to STDERR directly.
- All fields are read from the metadata, and corrupted files can often have
  incorrect values for length. TagLib does not actually parse the music stream
  to find this out.
- Tags are read at object initialization time. This means that if some other
  process modifies the tags on the music file, you won't see changes unless you
  create a new object.

{'fraction_non_alphanumeric': 0.07256153144940747, 'fraction_numerical': 0.01349134001823154, 'mean_word_length': 3.7996500437445317, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5571980', 'n_tokens_mistral': 1722, 'n_tokens_neox': 1635, 'n_words': 858}