Introduction
Encoding of PCM’s to format that is of smaller file size
became very popular in the early 1990’s due to the growing desire to share
audio files over the internet. Adding of track and album information to the
files became also necessary and between mid-1990’s – the late 1990’s a group
released what is known as ID3
.
ID3
is a metadata (which contains information like artist,
album, track length, album art, track number, genre, etc.) stored as chunks of
data either at the beginning (ID3v2
) or end (ID3v1
) of the media file.
id3lib is an open source, cross-platform, software
development library for reading, writing, and manipulating ID3v1
and ID3v2
tags.
This wrapper was written to ease working with id3lib.
Setting up your development environment
If you already know how to setup your development
environment to link with id3lib, you can skip to the second part of this
section.
Firstly, get the
id3lib archive attached to this article (you can also get it from
sourceforge.net/projects/id3lib/files/). The archive should contain a folder
named “id3”, a header file named “id3.h”, a dll named “id3lib.dll”, an export
library file named “id3lib.exp” and an Object File Library named “id3lib.lib”.
Extract the archive.
- In Visual Studio, go to the Project menu then to
Property Pages (<your project name> Property Pages). When the window
opens, go to the Configuration Properties tab, then to the Linker section,
under the Additional Library Directories, add the path of where you extract the
archive to as the value
- Then go to the c/c++ tab and under Additional
Include Directories, also add the extract path as it value
- Then go to the extract path and copy the
id3lib.dll file to the Output directory of your project or to your system32
folder.
Your environment is ready for id3lib library. The id3lib.dll
will have to be bundled will your executable.
Secondly, get the tagHelper_dd_mm_yyyy.zip archive attached to this article, extract it and copy the two files (tagHelper.h and tagHelper.cpp) to your project.
#include
the header to your project
#include "tagHelper.h"
Using the wrapper
To use the wrapper, you will have to call the constructor with the filename of the media file you want to work on.
#include "tagHelper.h"
int main()
{
tagHelper th("c:/started.mp3");
return 0;
}
Reading Values
Various values can be read / gotten using the wrapper, this range from the file size, to the MPEGLayer
of the mp3 file, to the channel
information, to the title, artist, even to the albumart. ;-)
Get information (without using the getValue()
method)
The following information about the media file can be gotten without the use of the
getValue()
method of the wrapper; hasLyrics(); hasV1Tag();hasV2Tag(); fileSize(); getMPEGLayer(); getMPEGVersion(); getMP3ChannelMode(); getCbrBitRate(); getVbrBitRate(); getFrequency(); getSampleRate(); getTrackLength();
and getMP3Header();
They are all members of the wrapper and their name suggests what they do
tagHelper th("c:/started.mp3");
MP3_BitRates cbr;
cbr = th.getCbrBitRate();
printf("The cbr bitrate is: %i\n", cbr);
Mp3_ChannelMode channel;
channel = th.getMP3ChannelMode();
printf("The channel mode is: %i\n", channel);
uint32 length;
length = th.getTrackLength();
printf("The track length is: %isec\n", length);
Getting information with the getValue()
method
The getValue()
method of the wrapper can be used to get additional id3 tag information from the media file. The prototype of the getValue()
method is
char* tagHelper::getValue(ID3_FrameID);
The method returns the value stored in the specified ID3_FrameID
frame in character array. The ID3_FrameID
are constants defined in the global.h
header file that comes with the id3lib
package. They are defined between lines 231 and 326 with description of what each stands for.
getValue()
returns NULL
if the ID3_FrameID
specified is not present in the media file.
NOTE:
- Not all the
ID3_FrameID
are usable with getValue()
because not all of them "store" their value as character array. Only use getValue()
with those that accept character array. - It is the responsibility of the coder to free (
delete
) the memory returned by
getValue()
tagHelper th("c:/started.mp3");
char* genre;
genre = th.getValue(ID3FID_CONTENTTYPE);
printf("The genre is: %s\n", genre);
delete genre;
char* title;
title = th.getValue(ID3FID_TITLE);
printf("The title of the song is: %s\n", title);
delete title;
Setting Information
The setValue()
method can be used to create and or modify frames. The prototype is
void tagHelper::setValue(ID3_FrameID, char*);
The method takes 2 parameters; the ID3_FrameID
of the frame to update and the value to update it with. If the frame specified is not present in the media file, setValue()
creates it and write the value to it.
NOTE:
- Not all the
ID3_FrameID
are usable with setValue()
because not all of them "store" their value as character array. Only use setValue()
with those that accept character array.
tagHelper th("c:/started.mp3");
th.setValue(ID3FID_YEAR, "1986");
th.setValue(ID3FID_TRACKNUM, "02");
The Albumart
The albumart ID3FID_PICTURE
is one of such frame you can’t use getValue()
and setValue()
on because it content is not stored in character array (third time of saying that right?).
Adding albumart to your media file
The addAlbumart()
method is used to add albumart to a media file.
void tagHelper::addAlbumart(char*);
The method takes a parameter which is the path to the image file to set as the albumart. Note that if the path you specified does not exist, the frame is not updated. This means that if the media file contains an albumart before, it will not be removed.
tagHelper th("c:/started.mp3");
th.addAlbumart("c:/albumart.jpg");
Retrieving the albumart
The getAlbumart()
method is used to extract the albumart of a media file into an image file. This is very useful in players that displays albumarts.
bool tagHelper::getAlbumart(char*);
The method takes one parameter; where to save the extracted image. It returns true
if successful and false
if not.
tagHelper th("c:/started.mp3");
th.getAlbumart("c:/albumart_extracted.jpg");
Removing Tags (New)
Removing of tags might be necessary sometimes. This might range from removing unneeded information to removing personal information, or even to totally removing (stripping) all id3 tags.
removeTag()
The
removeTag()
method can be used to remove specific id3 tags from the media file.
bool tagHelper::removeTag(ID3_FrameID);
This will return
true
if successful and
false
if the tag is not present or unsuccessful.
tagHelper th("c:/started.mp3");
th.removeTag(ID3FID_TITLE);
th.removeTag(ID3FID_PICTURE);
removeAllTags()
This as it names imply removes all the id3 tags in the media file. BUT NOTE, it also removes the Mp3_Headerinfo
so be careful about using it.
However, some portion (if not all) of the Mp3_Headerinfo
seems to be recovered once the setValue()
method is used on a media file which removeAllTags() had been used on before
This is useful in the case of decoding an mp3 file into a wav file. It solves the problem of having to seek back and forth so as to remove the id3 portion of the file before trying to decode it, just removeAllTags()
the file and decode!
tagHelper th("c:/started.mp3");
th.removeAllTags();
History
13th of September, 2013
getFrequency();
removed as it same as getSampleRate();
- Tag Removing added (
bool removeTag(ID3_FrameID);
) - Stripping of all id3 tags added (
bool removeAllTags();
)
31st August, 2013 - Initial Release