Mp3tag Web Source description file syntax, Revisited (Unofficial)

Script overview

Mp3tag Web Source is for fetching informations for the album (not for the single track) from the public webpage or JSON API.

❕ Commands for JSON will not be covered in this page for now.

Mostly, you will go through three steps below to implement a tag source of the service you want to use.

1. Define source properties
   Firstly, you will describe some definitions ([Key]=Value) which contain,

   • Source name
   • Search/album URLs to fetch the information
   • Character encoding of the HTML/JSON document to be fetched

2. Write the ParserScriptIndex (optional)
   Then, you will write the script to parse a search result from search index URL with search keyword (as name suggests).

   • If you want to fetch album information (or call ParserScriptAlbum) directly without ParserScriptIndex,
     • Do not define the IndexURL property
     • In this case, search keyword (SearchBy) will be appended after AlbumUrl when fecthing an album information.

3. Write the ParserScriptAlbum
   Finally, you will write the script to parse a fetched result from album information URL (as name suggests).

💡 Start your parser scripts with debug "on" "<path to log file>" when you are implementing that script.

Properties in script properties

• Wrap the property name with brackets ([ ])
• '#' character in Name will make submenu
  • e.g. Bugs#Search will make Search subcommand under Bugs menu item.

Property	Description
Name*	As name suggests.
BasedOn	Just for reference, not effective in functioning
IndexUrl	Url to fetch the search result. %s will be replaced with SearchBy formatted string
AlbumUrl*	Url to fetch the album information. The appended string will be differ, see below.
WordSeparator*	In query request, whitespaces in the generated url will be replaced with this value. e.g. +
IndexFormat*	"|" separated format for each record in ParserScriptIndex result. Please follow defined format in ParserScriptIndex.
SearchBy	Formatted string to be used as '%s' in "IndexUrl", e.g. "%title%"
Encoding	One of {url-utf-8, '', '', ''}
UserAgent	0 or (undefined) -> "Mozilla/5.0 (compatible)", 1 -> "Mp3tag/<version>"
(*)	(required)

About AlbumUrl

At the end of AlbumUrl, below parameter string will be appended to fetch the required data.

❔ From my knowledge, you cannot put the parameter between the AlbumUrl string, unlike you did for IndexUrl with %s placeholder. It seems that you have to make the ParserScriptIndex script returns the parameter for target album and url string after the position you want to put the parameter in.

IndexURL and ParserScriptIndex was not stated

The SearchBy formatted string will become the parameter to be appended.

Example

If the description file contains below definitions but not contains IndexURL,

[AlbumUrl]=https://peng.soo/
[SearchBy]=%album%

If your album tag has rocks, then Mp3tag will get the album information page from below URL:

https://peng.soo/rocks

IndexURL and ParserScriptIndex was stated

The %_url% defined in the IndexFormat will be appended to your AlbumUrl.

Example

If the description file contains below definitions,

[AlbumUrl]=https://peng.soo/
[IndexFormat]=%_url%|...(omitted)

If you choose one of the item returned from ParserScriptIndex, and that item has below index string,

rocks|...(omitted)

"rocks" will be fetched as %_url%, then Mp3tag will get the album information page from below URL:

https://peng.soo/rocks

Definitions Example 1

[Name]=Bugs / Search for track title
[BasedOn]=https://music.bugs.co.kr
[IndexUrl]=https://m.bugs.co.kr/search/track?q=%s
[AlbumUrl]=https://music.bugs.co.kr/album/
[WordSeparator]=+
[IndexFormat]=%_url%|%_preview%|%title%|%artist%
[SearchBy]=%title%
[Encoding]=url-utf-8

Definitions Example 2 without ParserScriptIndex

[Name]=Bugs / Track ID to lyric
[BasedOn]=https://music.bugs.co.kr
[AlbumUrl]=https://music.bugs.co.kr/track/
[WordSeparator]=+
[SearchBy]=%BugsTrackId%
[Encoding]=utf-8

Pitfall

• The keyword endif must be in lower case! ref
• In Windows, newline should be CR+LF (\r\n), not just LF (\n)
• If you want to show multiple tracks from ParserScriptAlbum, make sure the last SayOutput says multiple items
  (e.g. Now,We|Cameo|Aya|..., rather than single one Now,We or empty one ``)