kiwilan/php-audio

PHP package to parse and update audio files metadata, with `JamesHeinrich/getID3`.

4.0.01 2024-10-03 16:57 UTC

Requires

• php: ^8.1
• james-heinrich/getid3: ^v1.9.22

Requires (Dev)

• laravel/pint: ^1.2
• pestphp/pest: ^2.0
• phpstan/phpstan: ^1.12
• spatie/ray: ^1.28

MIT

• Ewilan Rivière

• php
• audio
• music
• id3
• mp3
• wav
• mp4
• webm
• ogg
• tta
• mkv
• id3v1
• id3v2
• flac
• wma
• opus
• alac
• m4v
• audiobook
• aif
• aifc
• aiff
• mka
• m4a
• m4b
• spx
• wv

README

PHP package to parse and update audio files metadata, with JamesHeinrich/getID3.

Note

You can check formats supported on Supported formats section.

About

Audio files can use different formats, this package aims to provide a simple way to read them with JamesHeinrich/getID3. The JamesHeinrich/getID3 package is excellent to read metadata from audio files, but output is just an array, current package aims to provide a simple way to read audio files with a beautiful API.

Requirements

• PHP 8.1 minimum
• Optional for update
  • FLAC: flac (with apt, brew or scoop)
  • OGG: vorbis-tools (with apt or brew) / extras/icecast (with scoop)

Roadmap

• Add support for more formats with external packages

Installation

You can install the package via composer:

composer require kiwilan/php-audio

Usage

Core metadata:

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');

$audio->getTitle(); // `?string` to get title
$audio->getArtist(); // `?string` to get artist
$audio->getAlbum(); // `?string` to get album
$audio->getGenre(); // `?string` to get genre
$audio->getYear(); // `?int` to get year
$audio->getTrackNumber(); // `?string` to get track number
$audio->getComment(); // `?string` to get comment
$audio->getAlbumArtist(); // `?string` to get album artist
$audio->getComposer(); // `?string` to get composer
$audio->getDiscNumber(); // `?string` to get disc number
$audio->isCompilation(); // `bool` to know if is compilation
$audio->getCreationDate(); // `?string` to get creation date
$audio->getCopyright(); // `?string` to get copyright
$audio->getEncoding(); // `?string` to get encoding
$audio->getDescription(); // `?string` to get description
$audio->getSynopsis(); // `?string` to get synopsis
$audio->getLanguage(); // `?string` to get language
$audio->getLyrics(); // `?string`
$audio->getDuration(); // `?float` to get duration in seconds
$audio->getDurationHuman(); // `?string` to get duration in human readable format

Raw tags:

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');

$raw_all = $audio->getRawAll(); // `array` with all tags
$raw = $audio->getRaw(); // `array` with main tag
$title = $audio->getRawKey('title'); // `?string` to get title same as `$audio->getTitle()`

$format = $audio->getRaw('id3v2'); // `?array` with all tags with format `id3v2`
$title = $audio->getRawKey('title', 'id3v2'); // `?string` to get title with format `id3v2`

Additional metadata:

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');

$audio->getPath(); // `string` to get path
$audio->getExtension(); // `string` to get extension
$audio->hasCover(); // `bool` to know if has cover
$audio->isValid(); // `bool` to know if file is valid audio file
$audio->isWritable(); // `bool` to know if file is writable
$audio->getFormat(); // `AudioFormatEnum` to get format (mp3, m4a, ...)
$audio->getType(); // `?AudioTypeEnum` ID3 type (id3, riff, asf, quicktime, matroska, ape, vorbiscomment)

You can use toArray() method to get raw info:

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');

$audio->toArray(); // `array` with all metadata

Advanced properties:

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');

$audio->getId3Reader(); // `?Id3Reader` reader based on `getID3`
$audio->getMetadata(); // `?AudioMetadata` with audio metadata
$audio->getCover(); // `?AudioCover` with cover metadata

Update

You can update audio files metadata with Audio::class, but not all formats are supported. See supported formats

Warning

You can use any property of Audio::class but if you use a property not supported by the format, it will be ignored.

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');
$audio->getTitle(); // `Title`

$tag = $audio->write()
  ->title('New Title')
  ->artist('New Artist')
  ->album('New Album')
  ->genre('New Genre')
  ->year('2022')
  ->trackNumber('2/10')
  ->albumArtist('New Album Artist')
  ->comment('New Comment')
  ->composer('New Composer')
  ->creationDate('2021-01-01')
  ->description('New Description')
  ->synopsis('New Synopsis')
  ->discNumber('2/2')
  ->encodingBy('New Encoding By')
  ->encoding('New Encoding')
  ->isCompilation()
  ->lyrics('New Lyrics')
  ->cover('path/to/cover.jpg') // you can use file content `file_get_contents('path/to/cover.jpg')`
  ->save();

$audio = Audio::read('path/to/audio.mp3');
$audio->getTitle(); // `New Title`
$audio->getCreationDate(); // `null` because `creationDate` is not supported by `MP3`

Some properties are not supported by all formats, for example MP3 can't handle some properties like lyrics or stik, if you try to update these properties, they will be ignored.

Set tags manually

You can set tags manually with tag() or tags() methods, but you need to know the format of the tag, you could use tagFormats to set formats of tags (if you don't know the format, it will be automatically detected).

Warning

If you use tags method, you have to use key used by metadata container. For example, if you want to set album artist in id3v2, you have to use band key. If you want to know which key to use check src/Core/AudioCore.php file.

If your key is not supported, save method will throw an exception, unless you use skipErrors.

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');
$audio->getAlbumArtist(); // `Band`

$tag = $audio->write()
    ->tag('composer', 'New Composer')
    ->tag('genre', 'New Genre') // can be chained
    ->tags([
        'title' => 'New Title',
        'band' => 'New Band', // `band` is used by `id3v2` to set album artist, method is `albumArtist` but `albumArtist` key will throw an exception with `id3v2`
    ])
    ->tagFormats(['id3v1', 'id3v2.4']) // optional
    ->save();

$audio = Audio::read('path/to/audio.mp3');
$audio->getAlbumArtist(); // `New Band`

Arrow functions

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');
$audio->getAlbumArtist(); // `Band`

$tag = $audio->write()
  ->title('New Title')
  ->albumArtist('New Band') // `albumArtist` will set `band` for `id3v2`, exception safe
  ->save();

$audio = Audio::read('path/to/audio.mp3');
$audio->getAlbumArtist(); // `New Band`

Skip errors

You can use skipErrors to prevent exception if you use unsupported format.

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');

$tag = $audio->write()
  ->tags([
    'title' => 'New Title',
    'title2' => 'New title', // not supported by `id3v2`, will throw an exception
  ])
  ->skipErrors() // will prevent exception
  ->save();

Note

Arrow functions are exception safe for properties but not for unsupported formats.

Raw tags

Audio files format metadata with different methods, JamesHeinrich/getID3 offer to check these metadatas by different methods. In raw_all property of Audio::class, you will find raw metadata from JamesHeinrich/getID3 package, like id3v2, id3v1, riff, asf, quicktime, matroska, ape, vorbiscomment...

If you want to extract specific field which can be skipped by Audio::class, you can use raw_all property.

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');
$raw_all = $audio->getRawAll(); // all formats
$raw = $audio->getRaw(); // main format

AudioMetadata

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');
$metadata = $audio->getMetadata();

$metadata->getFileSize(); // `?int` in bytes
$metadata->getSizeHuman(); // `?string` (1.2 MB, 1.2 GB, ...)
$metadata->getExtension(); // `?string` (mp3, m4a, ...)
$metadata->getEncoding(); // `?string` (UTF-8...)
$metadata->getMimeType(); // `?string` (audio/mpeg, audio/mp4, ...)
$metadata->getDurationSeconds(); // `?float` in seconds
$metadata->getDurationReadable(); // `?string` (00:00:00)
$metadata->getBitrate(); // `?int` in kbps
$metadata->getBitrateMode(); // `?string` (cbr, vbr, ...)
$metadata->getSampleRate(); // `?int` in Hz
$metadata->getChannels(); // `?int` (1, 2, ...)
$metadata->getChannelMode(); // `?string` (mono, stereo, ...)
$metadata->isLossless(); // `bool` to know if is lossless
$metadata->getCompressionRatio(); // `?float`
$metadata->getFilesize(); // `?int` in bytes
$metadata->getSizeHuman(); // `?string` (1.2 MB, 1.2 GB, ...)
$metadata->getDataFormat(); // `?string` (mp3, m4a, ...)
$metadata->getWarning(); // `?array`
$metadata->getQuicktime(); // `?Id3AudioQuicktime
$metadata->getCodec(); // `?string` (mp3, aac, ...)
$metadata->getEncoderOptions(); // `?string`
$metadata->getVersion(); // `?string`
$metadata->getAvDataOffset(); // `?int` in bytes
$metadata->getAvDataEnd(); // `?int` in bytes
$metadata->getFilePath(); // `?string`
$metadata->getFilename(); // `?string`
$metadata->getLastAccessAt(); // `?DateTime`
$metadata->getCreatedAt(); // `?DateTime`
$metadata->getModifiedAt(); // `?DateTime`
$metadata->toArray();

Quicktime

For quicktime type, like for M4B audiobook, you can use Id3TagQuicktime to get more informations.

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.m4b');
$quicktime = $audio->getMetadata()->getQuicktime();

$quicktime->getHinting();
$quicktime->getController();
$quicktime->getFtyp();
$quicktime->getTimestampsUnix();
$quicktime->getTimeScale();
$quicktime->getDisplayScale();
$quicktime->getVideo();
$quicktime->getAudio();
$quicktime->getSttsFramecount();
$quicktime->getComments();
$quicktime->getFree();
$quicktime->getWide();
$quicktime->getMdat();
$quicktime->getEncoding();
$quicktime->getChapters(); // ?Id3AudioQuicktimeChapter[]

AudioCover

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');
$cover = $audio->getCover();

$cover->getContents(); // `?string` raw file
$cover->getMimeType(); // `?string` (image/jpeg, image/png, ...)
$cover->getWidth(); // `?int` in pixels
$cover->getHeight(); // `?int` in pixels

Supported formats

Readable formats

• id3v2 will be selected before id3v1 or riff if both are available.

You want to add a format? See FAQ

Updatable formats

JamesHeinrich/getID3 can update some formats, but not all.

• ID3v1 (v1 & v1.1)
• ID3v2 (v2.3, v2.4)
• APE (v2)
• Ogg Vorbis comments (need vorbis-tools)
• FLAC comments (need flac)

• flac: with apt, brew or scoop
• vorbis-tools: with apt, brew or scoop
  • With scoop, vorbis-tools is not available, you can use extras/icecast instead.

Convert properties

Audio::class convert some properties to be more readable.

• ape format: Id3TagApe
• asf format: Id3TagAsf
• id3v1 format: Id3TagAudioV1
• id3v2 format: Id3TagAudioV2
• matroska format: Id3TagMatroska
• quicktime format: Id3TagQuicktime
• vorbiscomment format: Id3TagVorbisComment
• riff format: Id3TagRiff
• unknown format: Id3TagVorbisComment

Testing

composer test

Tools

• ffmpeg: free and open-source software project consisting of a suite of libraries and programs for handling video, audio, and other multimedia files and streams.
• MP3TAG: powerful and easy-to-use tool to edit metadata of audio files (free on Windows).
• Audiobook Builder: makes it easy to turn audio CDs and files into audiobooks (only macOS and paid).
• Tag Editor: A tag editor with Qt GUI and command-line interface supporting MP4/M4A/AAC (iTunes), ID3, Vorbis, Opus, FLAC and Matroska.
• Tag Editor: a spreadsheet application for editing audio metadata in a simple, fast, and flexible way.

FAQ

I have a specific metadata field in my audio files, what can I do?

In Audio::class, you have a property raw_all which contains all raw metadata, if JamesHeinrich/getID3 support this field, you will find it in this property.

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');
$raw_all = $audio->getRawAll());

$custom = null;
$id3v2 = $raw_all['id3v2'] ?? [];

if ($id3v2) {
  $custom = $id3v2['custom'] ?? null;
}

If your field could be added to global properties of Audio::class, you could create an an issue.

Metadata are null, what can I do?

You can check extras property to know if some metadata are available.

use Kiwilan\Audio\Audio;

$audio = Audio::read('path/to/audio.mp3');

$raw_all = $audio->getRawAll();
var_dump($raw_all);

If you find metadata which are not parsed by Audio::class, you can create an issue, otherwise JamesHeinrich/getID3 doesn't support this metadata.z

My favorite format is not supported, what can I do?

You can create an issue with the format name and a link to the format documentation. If JamesHeinrich/getID3 support this format, I will add it to this package but if you want to contribute, you can create a pull request with the format implementation.

Please give me an example file to test the format.

I have an issue with a supported format, what can I do?

You can create an issue with informations.

How to convert audio files?

This package doesn't provide a way to convert audio files, but you can use ffmpeg to convert audio files and PHP-FFMpeg/PHP-FFMpeg.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• ewilan-riviere: package author
• JamesHeinrich/getID3: parser used to read audio files
• spatie/package-skeleton-php: package skeleton used to create this package

License

The MIT License (MIT). Please see License File for more information.