Introduction

DigiTag is a 32-bit programming library that provides Clarion applications with a procedural interface for reading and writing MP3 metadata and retrieving MP3 audio properties.

DigiTag uses the TagLib library internally. No knowledge of TagLib or C++ is required.


What does DigiTag Do?

DigiTag allows Clarion applications to:

oRead and write common MP3 metadata tags.

oRetrieve duration, bitrate, sample rate, and channel information.

oRead or write multiple tags in a single operation.

oSynchronize Artist and Album Artist tags.

DigiTag provides a simple procedural interface to these functions without requiring direct access to TagLib or C++.


Which MP3 Tags Can DigiTag Get/Set?

MP3 Tag | Read | Write
Album | ✓ | ✓
Album Artist | ✓ | ✓
Artist | ✓ | ✓
Comment | ✓ | ✓
Composer | ✓ | ✓
Conductor | ✓ | ✓
Disc | ✓ | ✓
Disc Total | ✓ | ✓
Genre | ✓ | ✓
Title | ✓ | ✓
Track | ✓ | ✓
Track Total | ✓ | ✓
Year | ✓ | ✓

DigiTag can also read the MP3's Duration, Bitrate, Sample Rate, and Channels.


Clarion Version(s) Supported

DigiTag was developed and tested using Clarion 12.

Earlier Clarion versions have not been tested. DigiTag requires a 32-bit Clarion application.


Prerequisites

DigiTag requires:

oA 32-bit Clarion application.

oDigiTag.dll.

oTag.dll (TagLib runtime library).

oDigiTag.lib (Clarion import library).

No separate TagLib installation is required.


TagLib

TagLib is an open-source C++ library for reading and writing audio metadata. It supports MP3 and numerous other audio formats and has been under development since 2002.

DigiTag 1.0 uses TagLib 2.3.2. The supplied 32-bit Windows tag.dll was built by Software by Daughtry from the official TagLib 2.3.2 source using CMake and Microsoft Visual C++.

DigiTag accesses TagLib internally; Clarion applications do not call TagLib directly.

TagLib is distributed under the GNU LGPL and Mozilla Public License (MPL).

TagLib Website: taglib.org

TagLib Source: Official TagLib GitHub repository


DigiTag Files

DigiTag consists of three files:

File | Purpose
DigiTag.dll | DigiTag runtime library containing the MP3 metadata functions.
Tag.dll | 32-bit TagLib runtime library used internally by DigiTag.
DigiTag.lib | Clarion import library used when building the application.

Both DigiTag.dll and tag.dll must be distributed with the compiled Clarion application.

DigiTag.lib is required only during development and does not need to be distributed with the application.


DigiTag Setup

Adding DigiTag to a Clarion application requires:

a.Place the DigiTag runtime and import library files in the appropriate locations.

b.Add DigiTag.lib to the Clarion project.

c.Add the DigiTag function declarations to the application's Global Map.

The following topics describe each step.


Overview

DigiTag setup is performed once for each Clarion application. The setup consists of:

a.Placing the DigiTag files in the required locations.

b.Adding DigiTag.lib to the Clarion project.

c.Adding the DigiTag declarations to the application's Global Map.

No DigiTag initialization code is required.


DigiTag File Placement

Place the DigiTag files as follows:

File | Location
DigiTag.lib | Clarion Accessories\Lib folder
DigiTag.dll | Same folder as the compiled application (.EXE)
Tag.dll | Same folder as the compiled application (.EXE)

For example:

C:\Clarion12\Accessories\Lib\DigiTag.lib
C:\MyApplication\DigiTag.dll
C:\MyApplication\tag.dll
C:\MyApplication\MyApplication.exe

Both DLL files must be present in the application folder when the Clarion application is run.


Project Solution Explorer

Add DigiTag.lib to the Clarion application's Libraries, Objects and Resource Files section in the Solution Explorer. Right click the "Libraries, Objects, and Resource Files" entry in the Solution Explorer. A standard Windows file selection popup window appears to navigate to/select the DigiTag.lib file (which should be located in your LIB folder; for example: D:\Clarion12\Accessory\Lib\DigiTag.Lib)

Only DigiTag.lib is added to the project. DigiTag.dll and Tag.dll are runtime files and are not added to the Solution Explorer.


Global Map Embed

a. Open the Clarion application.

b. Select the Global Embeds tab.

c. Select Inside the Global Map, click Insert, select Source, then click Select.

d. Open the newly created Source embed.

e. Copy the complete DigiTag declaration block below into the Source embed:

! DigiTag globals needed to extract MP3 tags

MODULE('DigiTag.dll')

! Audio Properties

DT_GetDuration(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetDuration')

DT_GetBitrate(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetBitrate')

DT_GetSampleRate(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetSampleRate')

DT_GetChannels(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetChannels')

! Standard Tag Readers

DT_GetTitle(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetTitle')

DT_GetArtist(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetArtist')

DT_GetAlbumArtist(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetAlbumArtist')

DT_GetAlbum(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetAlbum')

DT_GetGenre(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetGenre')

DT_GetComment(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetComment')

DT_GetYear(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetYear')

DT_GetTrack(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetTrack')

! Standard Tag Writers

DT_SetTitle(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetTitle')

DT_SetArtist(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetArtist')

DT_SetArtistSync(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_SetArtistSync')

DT_SetAlbumArtist(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetAlbumArtist')

DT_SetAlbum(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetAlbum')

DT_SetGenre(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetGenre')

DT_SetComment(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetComment')

DT_SetYear(*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_SetYear')

DT_SetTrack(*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_SetTrack')

! Extended Core Tag Readers

DT_GetDisc(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetDisc')

DT_GetDiscTotal(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetDiscTotal')

DT_GetTrackTotal(*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_GetTrackTotal')

! Extended Core Tag Writers

DT_SetDisc(*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_SetDisc')

DT_SetDiscTotal(*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_SetDiscTotal')

DT_SetTrackTotal(*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_SetTrackTotal')

! Batch read tags

DT_ReadTags(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_ReadTags')

DT_WriteTags(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_WriteTags')

! Composer

DT_GetComposer(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetComposer')

DT_SetComposer(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetComposer')

! Conductor

DT_GetConductor(*CSTRING,*CSTRING,LONG),LONG,C,RAW,DLL(1),NAME('DT_GetConductor')

DT_SetConductor(*CSTRING,*CSTRING),LONG,C,RAW,DLL(1),NAME('DT_SetConductor')

END


DigiTag Function Reference

DigiTag provides 33 functions grouped into four categories:

·Audio Property Functions — Retrieve technical information about an MP3 file.

·Batch Functions — Read or write multiple MP3 tags in a single operation.

·Tag Reader Functions — Read individual MP3 tags.

·Tag Writer Functions — Write, change, or clear individual MP3 tags.

Select a function from the Table of Contents for its syntax, parameters, return value, and example.


Audio Property Functions

Audio Property functions retrieve technical information from an MP3 file.

Function | Returns
DT_GetDuration | Duration in seconds
DT_GetBitrate | Bitrate in kbps
DT_GetSampleRate | Sample rate in Hz
DT_GetChannels | Number of audio channels

These functions do not modify the MP3 file.


DT_GetDuration

Returns the duration of an MP3 file in seconds.

Syntax

DT_GetDuration(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Duration of the MP3 file in seconds.

Example

DTFileName = 'C:\Music\Song.mp3'
DTDuration = DT_GetDuration(DTFileName)

DTDuration is declared as a LONG.


DT_GetBitrate

Returns the bitrate of an MP3 file in kilobits per second (kbps).

Syntax

DT_GetBitrate(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Bitrate of the MP3 file in kbps.

Example

DTFileName = 'C:\Music\Song.mp3'
DTBitrate = DT_GetBitrate(DTFileName)

DTBitrate is declared as a LONG.


DT_GetSampleRate

Returns the sample rate of an MP3 file in Hertz (Hz).

Syntax

DT_GetSampleRate(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Sample rate of the MP3 file in Hz.

Example

DTFileName = 'C:\Music\Song.mp3'
DTSampleRate = DT_GetSampleRate(DTFileName)

DTSampleRate is declared as a LONG.


DT_GetChannels

Returns the number of audio channels in an MP3 file.

Syntax

DT_GetChannels(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Number of audio channels in the MP3 file.

Example

DTFileName = 'C:\Music\Song.mp3'
DTChannels = DT_GetChannels(DTFileName)

DTChannels is declared as a LONG.


Batch Functions

Batch functions allow multiple MP3 tags to be read or written in a single operation.

Function | Purpose
DT_ReadTags | Reads multiple MP3 tags and audio properties
DT_WriteTags | Writes, changes, or clears multiple MP3 tags

The batch functions are designed for applications that process large numbers of MP3 files, such as music cataloging, library scanning, importing, or bulk tag maintenance.

Using individual DigiTag functions, each requested tag requires a separate call and may require the MP3 file to be opened and examined again. DT_ReadTags opens the MP3 file once and retrieves all supported tags and audio properties during that operation. Likewise, DT_WriteTags can make multiple tag changes and save the file in a single operation.

The processing savings can become significant when working with large collections. For example, importing 10,000 MP3 files and retrieving 17 values individually could require as many as 170,000 DigiTag calls. Using DT_ReadTags requires only 10,000 calls — one per MP3 file.

For applications that routinely process large MP3 collections, the batch functions are therefore the preferred interface.


DT_ReadTags

Reads all supported MP3 tags and audio properties in a single operation.

The MP3 file is opened once and the retrieved values are returned in a serialized CSTRING. This function is recommended when several values are required from the same file or when processing large numbers of MP3 files.

Syntax

DT_ReadTags(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the serialized tag and audio-property data.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Return | Meaning
Positive value | Number of bytes returned
-1 | Invalid filename
-2 | Invalid output buffer
-3 | MP3 file could not be opened
-4 | Tag information unavailable
-5 | Output buffer too small

Returned Fields

DT_ReadTags returns 17 fields in the following order:

# | Field
1 | Title
2 | Artist
3 | Album Artist
4 | Album
5 | Genre
6 | Comment
7 | Composer
8 | Conductor
9 | Year
10 | Track
11 | Track Total
12 | Disc
13 | Disc Total
14 | Duration
15 | Bitrate
16 | Sample Rate
17 | Channels

Data Format

Each field is encoded as: <length>:<data>

length specifies the number of bytes contained in that field. Fields are placed immediately after one another, so embedded spaces or other characters in tag values do not interfere with parsing.

For example: 12:Swollen Rage17:10 Minute Warning...

The receiving Clarion code reads the length, extracts exactly that number of bytes, and then proceeds to the next field.

Example

Click here for example code


DT_WriteTags

Writes multiple MP3 tags in a single operation.

The MP3 file is opened once, the requested tag changes are applied, and the file is saved once. Each supported field can independently be left unchanged, set to a new value, or cleared.

DT_WriteTags is recommended when changing several tags in the same MP3 file or when performing bulk tag maintenance on large numbers of files.

Syntax

DT_WriteTags(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — CSTRING containing the serialized write instructions.

BufferSize — Size of the supplied input buffer. Use SIZE(Buffer) when calling DT_WriteTags.

Returns

Return | Meaning
1 | Tags were successfully modified and saved
0 | No fields were requested for modification
-1 | Invalid filename
-2 | Invalid input buffer
-3 | MP3 file could not be opened
-4 | Tag information unavailable
-5 | Malformed serialized data
-6 | Invalid operation
-7 | Invalid numeric value
-8 | MP3 file could not be saved

Writable Fields

DT_WriteTags accepts 13 fields in the following order:

# | Field
1 | Title
2 | Artist
3 | Album Artist
4 | Album
5 | Genre
6 | Comment
7 | Composer
8 | Conductor
9 | Year
10 | Track
11 | Track Total
12 | Disc
13 | Disc Total

Data Format

Each field is encoded as: <length>:<operation><value>

The first character of the field data specifies the operation:

Operation | Action
0 | Leave the existing value unchanged
1 | Set the field to the supplied value
2 | Clear the existing value

The field length includes the operation character.

Leave a field unchanged:

! Serialized field: 1:0
DTResult = DT_WriteTags(DTFileName,DTWriteData,SIZE(DTWriteData))

!1:0 means the field contains one byte of data (0), which instructs DigiTag to leave that field unchanged.

Clear a field:

! Serialized field: 1:2
DTResult = DT_WriteTags(DTFileName,DTWriteData,SIZE(DTWriteData))

!1:2 means the field contains one byte of data (2), which instructs DigiTag to clear that field.

Set Year to 2026:

! Serialized field: 5:12026
DTResult = DT_WriteTags(DTFileName,DTWriteData,SIZE(DTWriteData))

!5:12026 contains five bytes: the SET operation (1) followed by the four-byte value (2026).

These examples show the encoding of an individual field. DT_WriteTags expects DTWriteData to contain the complete serialized set of all 13 writable fields, in the required field order. Fields that are not being modified must still be represented using the UNCHANGED operation (1:0).

This design allows a single DT_WriteTags call to selectively modify some tags, clear others, and preserve all remaining tags.

Track and Disc Values

Track/Track Total and Disc/Disc Total are related tag values. DigiTag preserves their existing counterpart when appropriate.

For example, changing Track while leaving Track Total unchanged preserves the existing Track Total. Clearing Track removes the complete Track value, including Track Total.

The Disc and Disc Total fields can likewise be controlled independently.

Click here for example code


Tag Reader Functions

Tag Reader functions retrieve individual metadata values from an MP3 file.

Function | Returns
DT_GetTitle | Song title
DT_GetArtist | Artist
DT_GetAlbumArtist | Album Artist
DT_GetAlbum | Album title
DT_GetDisc | Disc number
DT_GetDiscTotal | Total number of discs
DT_GetGenre | Genre
DT_GetComment | Comment
DT_GetComposer | Composer
DT_GetConductor | Conductor
DT_GetTrackTotal | Total number of tracks
DT_GetYear | Year
DT_GetTrack | Track number

Tag Reader functions are useful when only one or a small number of metadata values are required from an MP3 file.

When several tags are required from the same file—or when processing large numbers of MP3 files—consider using DT_ReadTags instead. DT_ReadTags opens the file once and retrieves all supported tags and audio properties in a single operation, reducing the number of individual function calls and repeated file processing.


DT_GetTitle

Returns the Title tag from an MP3 file.

Syntax

DT_GetTitle(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Title.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetTitle(DTFileName,DTTitle,SIZE(DTTitle))
IF DTResult >= 0
MESSAGE('Title: ' & DTTitle)
END

DTTitle is declared as a CSTRING large enough to contain the returned Title.


DT_GetArtist

Returns the Artist tag from an MP3 file.

Syntax

DT_GetArtist(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Artist.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetArtist(DTFileName,DTArtist,SIZE(DTArtist))
IF DTResult >= 0
MESSAGE('Artist: ' & DTArtist)
END

DTArtist is declared as a CSTRING large enough to contain the returned Artist.


DT_GetAlbumArtist

Returns the Album Artist tag from an MP3 file.

Syntax

DT_GetAlbumArtist(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Album Artist.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetAlbumArtist(DTFileName,DTAlbumArtist,SIZE(DTAlbumArtist))
IF DTResult >= 0
MESSAGE('Album Artist: ' & DTAlbumArtist)
END

DTAlbumArtist is declared as a CSTRING large enough to contain the returned Album Artist.


DT_GetAlbum

Returns the Album tag from an MP3 file.

Syntax

DT_GetAlbum(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Album.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetAlbum(DTFileName,DTAlbum,SIZE(DTAlbum))
IF DTResult >= 0
MESSAGE('Album: ' & DTAlbum)
END

DTAlbum is declared as a CSTRING large enough to contain the returned Album.


DT_GetDisc

Returns the Disc number from an MP3 file.

Syntax

DT_GetDisc(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Disc number of the MP3 file.

If no Disc number is present, returns 0.

Example

DTFileName = 'C:\Music\Song.mp3'
DTDisc = DT_GetDisc(DTFileName)
MESSAGE('Disc: ' & DTDisc)

DTDisc is declared as a LONG.


DT_GetDiscTotal

Returns the total number of discs from an MP3 file.

Syntax

DT_GetDiscTotal(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Total number of discs specified in the MP3 file.

If no Disc Total value is present, returns 0.

Example

DTFileName = 'C:\Music\Song.mp3'
DTDiscTotal = DT_GetDiscTotal(DTFileName)
MESSAGE('Disc Total: ' & DTDiscTotal)

DTDiscTotal is declared as a LONG.


DT_GetGenre

Returns the Genre tag from an MP3 file.

Syntax

DT_GetGenre(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Genre.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetGenre(DTFileName,DTGenre,SIZE(DTGenre))
IF DTResult >= 0
MESSAGE('Genre: ' & DTGenre)
END

DTGenre is declared as a CSTRING large enough to contain the returned Genre.


DT_GetComment

Returns the Comment tag from an MP3 file.

Syntax

DT_GetComment(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Comment.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetComment(DTFileName,DTComment,SIZE(DTComment))
IF DTResult >= 0
MESSAGE('Comment: ' & DTComment)
END

DTComment is declared as a CSTRING large enough to contain the returned Comment.


DT_GetComposer

Returns the Composer tag from an MP3 file.

Syntax

DT_GetComposer(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Composer.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetComposer(DTFileName,DTComposer,SIZE(DTComposer))
IF DTResult >= 0
MESSAGE('Composer: ' & DTComposer)
END

DTComposer is declared as a CSTRING large enough to contain the returned Composer.


DT_GetConductor

Returns the Conductor tag from an MP3 file.

Syntax

DT_GetConductor(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Buffer — Caller-supplied CSTRING that receives the Conductor.

BufferSize — Size of the supplied output buffer.

Returns

On success, returns the number of bytes written to Buffer.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_GetConductor(DTFileName,DTConductor,SIZE(DTConductor))
IF DTResult >= 0
MESSAGE('Conductor: ' & DTConductor)
END

DTConductor is declared as a CSTRING large enough to contain the returned Conductor.


DT_GetTrackTotal

Returns the total number of tracks from an MP3 file.

Syntax

DT_GetTrackTotal(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Total number of tracks specified in the MP3 file.

If no Track Total value is present, returns 0.

Example

DTFileName = 'C:\Music\Song.mp3'
DTTrackTotal = DT_GetTrackTotal(DTFileName)
MESSAGE('Track Total: ' & DTTrackTotal)

DTTrackTotal is declared as a LONG.


DT_GetYear

Returns the Year from an MP3 file.

Syntax

DT_GetYear(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Year specified in the MP3 file.

If no Year value is present, returns 0.

Example

DTFileName = 'C:\Music\Song.mp3'
DTYear = DT_GetYear(DTFileName)
MESSAGE('Year: ' & DTYear)

DTYear is declared as a LONG.


DT_GetTrack

Returns the Track number from an MP3 file.

Syntax

DT_GetTrack(*CSTRING),LONG

Parameter

FileName — CSTRING containing the complete path and filename of the MP3 file.

Returns

Track number specified in the MP3 file.

If no Track value is present, returns 0.

Example

DTFileName = 'C:\Music\Song.mp3'
DTTrack = DT_GetTrack(DTFileName)
MESSAGE('Track: ' & DTTrack)

DTTrack is declared as a LONG.


Tag Writer Functions

Tag Writer functions modify individual metadata values in an MP3 file.

Function | Purpose
DT_SetTitle | Sets or clears the Title
DT_SetArtist | Sets or clears the Artist
DT_SetArtistSync | Sets Artist and optionally synchronizes Album Artist
DT_SetAlbumArtist | Sets or clears the Album Artist
DT_SetAlbum | Sets or clears the Album
DT_SetComposer | Sets or clears the Composer
DT_SetConductor | Sets or clears the Conductor
DT_SetDisc | Sets or clears the Disc number
DT_SetDiscTotal | Sets or clears the Disc Total
DT_SetGenre | Sets or clears the Genre
DT_SetComment | Sets or clears the Comment
DT_SetTrackTotal | Sets or clears the Track Total
DT_SetYear | Sets or clears the Year
DT_SetTrack | Sets or clears the Track number

Tag Writer functions are useful when only one or a small number of metadata values need to be changed.

Each function opens the MP3 file, performs the requested change, and saves the file. When several tags must be changed in the same file—or when processing large numbers of MP3 files—consider using DT_WriteTags instead.

DT_WriteTags can modify multiple tags and save the MP3 file in a single operation.

When a numeric tag supports clearing, passing 0 clears the corresponding value. String tags can be cleared by supplying an empty CSTRING.


DT_SetTitle

Sets or clears the Title tag in an MP3 file.

Syntax

DT_SetTitle(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Title — CSTRING containing the new Title. Supply an empty CSTRING to clear the existing Title.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTTitle = 'New Song Title'
DTResult = DT_SetTitle(DTFileName,DTTitle)
IF DTResult = 1
MESSAGE('Title successfully updated.')
END

DTTitle is declared as a CSTRING large enough to contain the new Title.


DT_SetArtist

Sets or clears the Artist tag in an MP3 file.

Syntax

DT_SetArtist(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Artist — CSTRING containing the new Artist. Supply an empty CSTRING to clear the existing Artist.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTArtist = 'New Artist'
DTResult = DT_SetArtist(DTFileName,DTArtist)
IF DTResult = 1
MESSAGE('Artist successfully updated.')
END

DTArtist is declared as a CSTRING large enough to contain the new Artist.


DT_SetArtistSync

Sets the Artist tag and optionally synchronizes the Album Artist tag to the same value.

Syntax

DT_SetArtistSync(*CSTRING,*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Artist — CSTRING containing the new Artist.

SyncAlbumArtist — Controls whether Album Artist is also changed:

Value | Action
0 | Set Artist only. Album Artist remains unchanged.
1 | Set both Artist and Album Artist to the supplied Artist.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTArtist = 'New Artist'
! Update both Artist and Album Artist
DTResult = DT_SetArtistSync(DTFileName,DTArtist,1)
IF DTResult = 1
MESSAGE('Artist and Album Artist successfully updated.')
END

Use DT_SetArtist when only the Artist tag needs to be changed. Use DT_SetArtistSync when Artist and Album Artist should contain the same value.


DT_SetAlbumArtist

Sets or clears the Album Artist tag in an MP3 file.

Syntax

DT_SetAlbumArtist(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

AlbumArtist — CSTRING containing the new Album Artist. Supply an empty CSTRING to clear the existing Album Artist.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTAlbumArtist = 'New Album Artist'
DTResult = DT_SetAlbumArtist(DTFileName,DTAlbumArtist)
IF DTResult = 1
MESSAGE('Album Artist successfully updated.')
END

DTAlbumArtist is declared as a CSTRING large enough to contain the new Album Artist.


DT_SetAlbum

Sets or clears the Album tag in an MP3 file.

Syntax

DT_SetAlbum(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Album — CSTRING containing the new Album. Supply an empty CSTRING to clear the existing Album.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTAlbum = 'New Album Title'
DTResult = DT_SetAlbum(DTFileName,DTAlbum)
IF DTResult = 1
MESSAGE('Album successfully updated.')
END

DTAlbum is declared as a CSTRING large enough to contain the new Album.


DT_SetComposer

Sets or clears the Composer tag in an MP3 file.

Syntax

DT_SetComposer(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Composer — CSTRING containing the new Composer. Supply an empty CSTRING to clear the existing Composer.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTComposer = 'New Composer'
DTResult = DT_SetComposer(DTFileName,DTComposer)
IF DTResult = 1
MESSAGE('Composer successfully updated.')
END

DTComposer is declared as a CSTRING large enough to contain the new Composer.


DT_SetConductor

Sets or clears the Conductor tag in an MP3 file.

Syntax

DT_SetConductor(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Conductor — CSTRING containing the new Conductor. Supply an empty CSTRING to clear the existing Conductor.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTConductor = 'New Conductor'
DTResult = DT_SetConductor(DTFileName,DTConductor)
IF DTResult = 1
MESSAGE('Conductor successfully updated.')
END

DTConductor is declared as a CSTRING large enough to contain the new Conductor.


DT_SetDisc

Sets or clears the Disc number in an MP3 file.

Syntax

DT_SetDisc(*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Disc — LONG containing the new Disc number. Specify 0 to clear the Disc number.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_SetDisc(DTFileName,2)
IF DTResult = 1
MESSAGE('Disc successfully updated.')
END

If a Disc Total value already exists, DT_SetDisc preserves that value when changing the Disc number.


DT_SetDiscTotal

Sets or clears the Disc Total in an MP3 file.

Syntax

DT_SetDiscTotal(*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

DiscTotal — LONG containing the new Disc Total. Specify 0 to clear the Disc Total.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_SetDiscTotal(DTFileName,3)
IF DTResult = 1
MESSAGE('Disc Total successfully updated.')
END

If a Disc number already exists, DT_SetDiscTotal preserves that value when changing the Disc Total.


DT_SetGenre

Sets or clears the Genre tag in an MP3 file.

Syntax

DT_SetGenre(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Genre — CSTRING containing the new Genre. Supply an empty CSTRING to clear the existing Genre.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTGenre = 'Hard Rock'
DTResult = DT_SetGenre(DTFileName,DTGenre)
IF DTResult = 1
MESSAGE('Genre successfully updated.')
END

DTGenre is declared as a CSTRING large enough to contain the new Genre.


DT_SetComment

Sets or clears the Comment tag in an MP3 file.

Syntax

DT_SetComment(*CSTRING,*CSTRING),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Comment — CSTRING containing the new Comment. Supply an empty CSTRING to clear the existing Comment.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTComment = 'New Comment'
DTResult = DT_SetComment(DTFileName,DTComment)
IF DTResult = 1
MESSAGE('Comment successfully updated.')
END

DTComment is declared as a CSTRING large enough to contain the new Comment.


DT_SetTrackTotal

Sets or clears the Track Total in an MP3 file.

Syntax

DT_SetTrackTotal(*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

TrackTotal — LONG containing the new Track Total. Specify 0 to clear the Track Total.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_SetTrackTotal(DTFileName,12)
IF DTResult = 1
MESSAGE('Track Total successfully updated.')
END

If a Track number already exists, DT_SetTrackTotal preserves that value when changing the Track Total.


DT_SetYear

Sets or clears the Year in an MP3 file.

Syntax

DT_SetYear(*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Year — LONG containing the new Year. Specify 0 to clear the Year.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_SetYear(DTFileName,2026)
IF DTResult = 1
MESSAGE('Year successfully updated.')
END

The Year value must be 0 or greater. Negative values are not accepted.


DT_SetTrack

Sets or clears the Track number in an MP3 file.

Syntax

DT_SetTrack(*CSTRING,LONG),LONG

Parameters

FileName — CSTRING containing the complete path and filename of the MP3 file.

Track — LONG containing the new Track number. Specify 0 to clear the Track number.

Returns

1 if the MP3 file was successfully modified and saved.

0 if the operation was unsuccessful.

Example

DTFileName = 'C:\Music\Song.mp3'
DTResult = DT_SetTrack(DTFileName,5)
IF DTResult = 1
MESSAGE('Track successfully updated.')
END

If a Track Total value already exists, DT_SetTrack preserves that value when changing the Track number.


DigiTag Return Codes

DigiTag functions return a LONG indicating the result of the requested operation.

Individual Tag Writer Functions

Return | Meaning
1 | MP3 file successfully modified and saved
0 | Operation was unsuccessful

DT_ReadTags

Return | Meaning
> 0 | Number of bytes returned in the output buffer
-1 | Invalid filename
-2 | Invalid output buffer
-3 | MP3 file could not be opened
-4 | Tag information unavailable
-5 | Output buffer too small

DT_WriteTags

Return | Meaning
1 | MP3 file successfully modified and saved
0 | No tag changes were requested
-1 | Invalid filename
-2 | Invalid input buffer
-3 | MP3 file could not be opened
-4 | Tag information unavailable
-5 | Malformed serialized data
-6 | Invalid write operation
-7 | Invalid numeric value
-8 | MP3 file could not be saved

Audio Property and Tag Reader Functions

Audio Property functions return the requested numeric value.

Numeric Tag Reader functions return the stored numeric value, or 0 when no value is present.

String Tag Reader functions return the number of bytes written to the caller-supplied output buffer on success.

Note: The Batch functions provide detailed negative return codes because they perform multiple operations and require serialized input or output buffers.


Navigation: »No topics above this level«

Return to chapter overview

DigiTag Code Examples

Enter topic text here.


Example: Parse DT_ReadTags Output

Purpose

This example illustrates how to parse the output of DT_ReadTags() and assign the 17 returned fields to individual Clarion variables.

Code

! These variables are declared as local data in the Window procedure.

DTFileName CSTRING(1024)

DTResult LONG

DTPos LONG

DTColonPos LONG

DTFieldLen LONG

DTFieldNo LONG

DTTitle CSTRING(1024)

DTArtist CSTRING(1024)

DTAlbumArtist CSTRING(1024)

DTAlbum CSTRING(1024)

DTGenre CSTRING(1024)

DTComment CSTRING(4096)

DTComposer CSTRING(1024)

DTConductor CSTRING(1024)

DTYear LONG

DTTrack LONG

DTTrackTotal LONG

DTDisc LONG

DTDiscTotal LONG

DTDuration LONG

DTBitrate LONG

DTSampleRate LONG

DTChannels LONG

DTTemp STRING(4096)

DTBatchData CSTRING(16384)

! Code below was inserted into a button that is passed a file name from a table control

! Explore/manipulate MP3 tag contents with TagLib

DTFileName = clip(FOL:FullPathName) & clip(FIL:Filename)

CLEAR(DTBatchData)

CLEAR(DTTemp)

DTResult = DT_ReadTags(DTFileName,DTBatchData,SIZE(DTBatchData))

IF DTResult > 0

DTPos = 1

LOOP DTFieldNo = 1 TO 17

DTColonPos = INSTRING(':',DTBatchData,1,DTPos)

IF DTColonPos = 0

BREAK

END

DTFieldLen = DTBatchData[DTPos : DTColonPos - 1]

DTPos = DTColonPos + 1

CLEAR(DTTemp)

IF DTFieldLen > 0

DTTemp = DTBatchData[DTPos : DTPos + DTFieldLen - 1]

DTPos += DTFieldLen

END

CASE DTFieldNo

OF 1

DTTitle = CLIP(DTTemp)

OF 2

DTArtist = CLIP(DTTemp)

OF 3

DTAlbumArtist = CLIP(DTTemp)

OF 4

DTAlbum = CLIP(DTTemp)

OF 5

DTGenre = CLIP(DTTemp)

OF 6

DTComment = CLIP(DTTemp)

OF 7

DTComposer = CLIP(DTTemp)

OF 8

DTConductor = CLIP(DTTemp)

OF 9

DTYear = DTTemp

OF 10

DTTrack = DTTemp

OF 11

DTTrackTotal = DTTemp

OF 12

DTDisc = DTTemp

OF 13

DTDiscTotal = DTTemp

OF 14

DTDuration = DTTemp

OF 15

DTBitrate = DTTemp

OF 16

DTSampleRate = DTTemp

OF 17

DTChannels = DTTemp

END

END

MESSAGE('Title: ' & CLIP(DTTitle) & |

'|Artist: ' & CLIP(DTArtist) & |

'|Album Artist: ' & CLIP(DTAlbumArtist) & |

'|Album: ' & CLIP(DTAlbum) & |

'|Genre: ' & CLIP(DTGenre) & |

'|Comment: ' & CLIP(DTComment) & |

'|Composer: ' & CLIP(DTComposer) & |

'|Conductor: ' & CLIP(DTConductor) & |

'|Year: ' & DTYear & |

'|Track: ' & DTTrack & |

'|Track Total: ' & DTTrackTotal & |

'|Disc: ' & DTDisc & |

'|Disc Total: ' & DTDiscTotal & |

'|Duration: ' & DTDuration & ' seconds' & |

'|Bitrate: ' & DTBitrate & ' kbps' & |

'|Sample Rate: ' & DTSampleRate & ' Hz' & |

'|Channels: ' & DTChannels, |

'DT_ReadTags Results')

ELSE

MESSAGE('DT_ReadTags failed. Return code: ' & DTResult, 'DigiTag Parsing Error')

END

! The resultant parsed data (note: the passed MP3 file had blank data for some fields, such as Comment and Composer)

After the loop completes, the 17 DigiTag values are available in their corresponding Clarion variables.

The serialized data should always be parsed using the supplied byte length rather than searching for delimiters within the tag data. This allows tag values to contain spaces, punctuation, colons, and other characters without affecting parsing.


Example: DT_WriteTags

Purpose

This example illustrates how to overwrite one MP3 tag field with DT_WriteTags()

Code

! These variables are declared as local data in the Window procedure.

DTFileName CSTRING(1024)

DTResult LONG

DTPos LONG

DTColonPos LONG

DTFieldLen LONG

DTFieldNo LONG

DTTitle CSTRING(1024)

DTArtist CSTRING(1024)

DTAlbumArtist CSTRING(1024)

DTAlbum CSTRING(1024)

DTGenre CSTRING(1024)

DTComment CSTRING(4096)

DTComposer CSTRING(1024)

DTConductor CSTRING(1024)

DTYear LONG

DTTrack LONG

DTTrackTotal LONG

DTDisc LONG

DTDiscTotal LONG

DTDuration LONG

DTBitrate LONG

DTSampleRate LONG

DTChannels LONG

DTTemp STRING(4096)

DTBatchData CSTRING(16384)

! Code below was inserted into a button that is passed a file name from a table control

! Explore/manipulate MP3 tag contents with TagLib

DTFileName = clip(FOL:FullPathName) & clip(FIL:Filename)

!=========================

CLEAR(DTWriteData)

! Title - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Artist - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Album Artist - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Album - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Genre - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Comment - SET to "Written by DigiTag"

DTWriteData = CLIP(DTWriteData) & '19:1Written by DigiTag'

! Composer - CLEAR

DTWriteData = CLIP(DTWriteData) & '1:2'

! Conductor - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Year - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Track - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Track Total - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Disc - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

! Disc Total - UNCHANGED

DTWriteData = CLIP(DTWriteData) & '1:0'

DTResult = DT_WriteTags(DTFileName,DTWriteData,SIZE(DTWriteData))

IF DTResult = 1

MESSAGE('DT_WriteTags completed successfully.' & |

'||Comment was SET to: Written by DigiTag' & |

'|Composer was CLEARED' & |

'|All other tags were left UNCHANGED', |

'DT_WriteTags Results')

ELSIF DTResult = 0

MESSAGE('No tag changes were requested.', |

'DT_WriteTags Results')

ELSE

MESSAGE('DT_WriteTags failed. Return code: ' & DTResult, |

'DigiTag Error')

END

Result


DigiTag Support

DigiTag is developed and maintained by Software by Daughtry.

For questions, bug reports, or problems using DigiTag, please contact Software by Daughtry.

When reporting a problem, please include:

·Clarion version

·DigiTag version

·Description of the problem

·DigiTag function being used

·Return code, if applicable

·A small code example demonstrating the problem

See Contact Us for contact information.


Contact Us

For DigiTag support, questions, or bug reports:

Software by Daughtry

Website: www.sdaughtry.com

Email: scott@sdaughtry.com

When contacting support regarding a problem, please include the DigiTag version, Clarion version, and any applicable DigiTag return code.