Merge pull request #2 from kiwilan/develop

1.0.0

Author: ewilan-riviere

README.md

@@ -8,10 +8,14 @@
 [![tests][tests-src]][tests-href]
 [![codecov][codecov-src]][codecov-href]
 
-PHP package to parse audio files metadata, with [JamesHeinrich/getID3](https://github.com/JamesHeinrich/getID3).
+PHP package to parse and update audio files metadata, with [`JamesHeinrich/getID3`](https://github.com/JamesHeinrich/getID3).
 
 ## Supported formats
 
+### Readable formats
+
+-   `id3v2` will be selected before `id3v1` or `riff` if both are available.
+
 | Format | Supported |                About                 |    ID3 type     |         Notes         |
 | :----: | :-------: | :----------------------------------: | :-------------: | :-------------------: |
 |  AAC   |    ❌     |        Advanced Audio Coding         |                 |                       |
@@ -24,7 +28,7 @@ PHP package to parse audio files metadata, with [JamesHeinrich/getID3](https://g
 |  MKA   |    ✅     |               Matroska               |   `matroska`    | _Cover not supported_ |
 |  MKV   |    ✅     |               Matroska               |   `matroska`    | _Cover not supported_ |
 |  APE   |    ❌     |            Monkey's Audio            |                 |                       |
-|  MP3   |    ✅     |          MPEG audio layer 3          | `id3v1`,`id3v2` |                       |
+|  MP3   |    ✅     |          MPEG audio layer 3          | `id3v2`,`id3v1` |                       |
 |  MP4   |    ✅     | Digital multimedia container format  |   `quicktime`   |                       |
 |  M4A   |    ✅     |             mpeg-4 audio             |   `quicktime`   |                       |
 |  M4B   |    ✅     |              Audiobook               |   `quicktime`   |                       |
@@ -44,13 +48,38 @@ PHP package to parse audio files metadata, with [JamesHeinrich/getID3](https://g
 
 You want to add a format? [See FAQ](#faq)
 
-## Requirements
+### Updatable formats
 
--   PHP >= 8.1
+`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
+
+| Format |         Notes         |
+| :----: | :-------------------: |
+|  FLAC  | _Cover not supported_ |
+|  MP3   |                       |
+|  OGG   | _Cover not supported_ |
+
+### Convert properties
+
+`Audio::class` convert some properties to be more readable.
+
+| ID3 type |    Original    | New property  |
+| :------: | :------------: | :-----------: |
+| `id3v2`  |     `band`     | `albumArtist` |
+| `id3v2`  | `track_number` | `trackNumber` |
 
 ## About
 
-Audio files can use different formats, this package aims to provide a simple way to read them with [JamesHeinrich/getID3](https://github.com/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.
+Audio files can use different formats, this package aims to provide a simple way to read them with [`JamesHeinrich/getID3`](https://github.com/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
 
 ## Installation
 
@@ -62,8 +91,10 @@ composer require kiwilan/php-audio
 
 ## Usage
 
+Core metadata:
+
 ```php
-$audio = Audio::read('path/to/audio.mp3');
+$audio = Audio::get('path/to/audio.mp3');
 
 $audio->title(); // `?string` to get title
 $audio->artist(); // `?string` to get artist
@@ -83,48 +114,80 @@ $audio->description(); // `?string` to get description (audiobook)
 $audio->lyrics(); // `?string` (audiobook)
 $audio->stik(); // `?string` (audiobook)
 $audio->duration(); // `?float` to get duration in seconds
+```
+
+Additional metadata:
+
+```php
+$audio = Audio::get('path/to/audio.mp3');
 
 $audio->path(); // `string` to get path
-$audio->extension(); // `string` to get extension
 $audio->hasCover(); // `bool` to know if has cover
 $audio->isValid(); // `bool` to know if file is valid audio file
+$audio->format(); // `AudioFormatEnum` to get format (mp3, m4a, ...)
+$audio->type(); // `?AudioTypeEnum` ID3 type (id3, riff, asf, quicktime, matroska, ape, vorbiscomment)
 
 $audio->extras(); // `array` with raw metadata (could contains some metadata not parsed)
-$audio->id3(); // `Id3` metadata
+$audio->reader(); // `?Id3Reader` reader based on `getID3`
+$audio->writer(); // `?Id3Writer` writer based on `getid3_writetags`
 $audio->stat(); // `FileStat` (from `stat` function)
 $audio->audio(); // `?AudioMetadata` with audio metadata
 $audio->cover(); // `?AudioCover` with cover metadata
 ```
 
+### Update
+
+You can update audio files metadata with `Audio::class`, but not all formats are supported. [See supported formats](#updatable-formats)
+
+```php
+$audio = Audio::get('path/to/audio.mp3');
+
+// you can use file content
+$cover = file_get_contents('path/to/cover.jpg');
+// or file path
+$cover = 'path/to/cover.jpg';
+
+$tag = $audio->update()
+  ->setTitle('New Title')
+  ->setArtist('New Artist')
+  ->setAlbum('New Album')
+  ->setGenre('New Genre')
+  ->setYear('2022')
+  ->setTrackNumber('2/10')
+  ->setAlbumArtist('New Album Artist')
+  ->setComment('New Comment')
+  ->setComposer('New Composer')
+  ->setCreationDate('2021-01-01')
+  ->setDescription('New Description')
+  ->setDiscNumber('2/2')
+  ->setEncodingBy('New Encoding By')
+  ->setEncoding('New Encoding')
+  ->setIsCompilation(false)
+  ->setLyrics('New Lyrics')
+  ->setStik('New Stik')
+  ->setCover($cover)
+  ->save();
+```
+
+Some properties are not supported by all formats, for example `MP3` can't handle `lyrics` or `stik` properties, if you try to update these properties, they will be ignored.
+
 ### Extras
 
 Audio files format metadata with different methods, `JamesHeinrich/getID3` offer to check these metadatas by different methods. In `extras` 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 `extras` property.
 
 ```php
-$audio = Audio::read('path/to/audio.mp3');
+$audio = Audio::get('path/to/audio.mp3');
 $extras = $audio->extras();
 
 $id3v2 = $extras['id3v2'] ?? [];
 ```
 
-### ID3
-
-Data from `JamesHeinrich/getID3` package with formatting.
-
-```php
-$audio = Audio::read('path/to/audio.mp3');
-
-$audio->id3()->raw(); // `array` with raw metadata
-$audio->id3()->item(); // `?Id3Item` with item metadata
-$audio->id3()->instance(); // `getID3` instance
-```
-
 ### AudioMetadata
 
 ```php
-$audio = Audio::read('path/to/audio.mp3');
+$audio = Audio::get('path/to/audio.mp3');
 
 $audio->audio()->filesize(); // `?int` in bytes
 $audio->audio()->extension(); // `?string` (mp3, m4a, ...)
@@ -144,7 +207,7 @@ $audio->audio()->compressionRatio(); // `?float`
 ### AudioCover
 
 ```php
-$audio = Audio::read('path/to/audio.mp3');
+$audio = Audio::get('path/to/audio.mp3');
 
 $audio->cover()->content(); // `?string` raw file
 $audio->cover()->mimeType(); // `?string` (image/jpeg, image/png, ...)
@@ -171,7 +234,7 @@ composer test
 In `Audio::class`, you have a property `extras` which contains all raw metadata, if `JamesHeinrich/getID3` support this field, you will find it in this property.
 
 ```php
-$audio = Audio::read('path/to/audio.mp3');
+$audio = Audio::get('path/to/audio.mp3');
 $extras = $audio->extras();
 
 $custom = null;

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "kiwilan/php-audio",
-    "description": "PHP package to parse audio files metadata.",
-    "version": "0.3.0",
+    "description": "PHP package to parse and update audio files metadata, with `JamesHeinrich/getID3`.",
+    "version": "1.0.0",
     "keywords": [
         "audio",
         "php",