[WS] iTunes source script with multiple search criteria

Development Web Sources Scripts
38

Now then, here is an overview of the currently available settings, as well as some comments on their purpose and how to use them:
(choices marked with "**" are the default ones for that setting)

  • "Interface" group

The settings in this group are meant to customize what is shown during a search. Tags generated by options in this group refer to outputs of current settings and are not meant to be written into music files.

# Query thumbnails (drop-box)

  • tool-tip: "Display cover preview thumbnails in query results in selected size. Large sizes may impact performance"
  • choices: [|Small (100x100px)**|Medium (250x250px)|Large (600x600px)]
  • additional info: Please note that the actual size of the thumbnail shown when hovering with the cursor is fixed; a higher resolution will result in a higher quality image, but in a query that returns many results the system load to show large-sized images can slow the search (or even return an error). 100x100px is the fastest option for showing thumbnails; 600x600px should only be used in queries with few hits, and if the details of the cover require high-quality previews.

# Tag data source (drop-box)

  • tool-tip: "Retrieve tag data from iTunes API or Apple Music webpage. Query results provided by iTunes API"
  • choices: [Apple Music Web|iTunes API**]
  • additional info: Despite being both owned by Apple, both iTunes and Apple Music (AM) have differences in the amount (and quality) of information provided for music collections. I recommend trying both and see which better suits your tagging needs. As a rule of thumb, iTunes API will return results faster, but has less tag fields available; Apple Music Web parses an entire album webpage to get the necessary info, so it will be slower (but will provide more info). I'll be posting a side-by-side comparison of fields from both sources, showcasing their similarities (and differences).

# Show "#_SOURCE" tag (checkbox)

  • tool-tip: "Display current source as a custom tag in "Metadata Album"
  • choices: [enabled|disabled**]
  • additional info: During development, sometimes I would be looking at search results and not remembering if I was in "iTunes API" mode or "Apple Music Web" mode. There are signs (number of tags returned, format of data returned, etc.) that can be used to tell the difference, but there isn't a field that states that setting clearly in the results (which makes sense, because this dual source script is an experiment, and Mp3Tag was never meant to support it). Checking this box will show a "#_SOURCE" tag in the results window (under "Metadata Album"), indicating what database was used in the search. This tag is NOT meant to be written in music files; if your tagging needs put you going back and forth between sources, I recommend checking this option BUT uncheck the "#_SOURCE" tag in the results, as to not write its value to your files (selections are memorized).

# Show "#_COVERURL" tag (checkbox)

  • tool-tip: "Display cover URL as a custom tag in "Metadata Album"
  • choices: [enabled|disabled**]
  • additional info: For the overhaul of cover art settings, I asked the Mp3Tag community for help, and among the many useful suggestions, I noticed that many users already have their own method for adding cover art to their collection, and have the need to access the cover art image file outside of Mp3Tag's workspace. This option, when enabled, will show the URL of the image file displayed in the results' window. Additionally, the settings in the "Cover" group are reflected in the "#_COVERURL" tag, so the URL will also show the currently defined cover size, quality and format. This tag is NOT meant to be written in music files, so if you plan to use it, remember to keep it unchecked in the results window.
  • "Cover" group

The settings in this group apply customized preferences to the cover art shown in the results' page, which can be written into music files. These settings are output in the "#_COVERURL" tag.

# Use unmodified cover image (checkbox)

  • tool-tip: "Request cover in original dimensions/quality/format from source. Ignores other cover options"
  • choices: [enabled|disabled**]
  • additional info: Both sources use the same database for cover art, and using arguments in the request URL, you can modify the resulting image. As the title says, checking this box will modify the request URL to get the unmodified version of the cover art image. If you want the best available image from the source, this is the only option you need to check (as it supersedes all others), but results will be varied. If you want consistent cover parameters across your collection, keep this unchecked and use the other options in the "Cover" group.

# Size (drop-box)

  • tool-tip: "Set cover dimensions. Source is responsible for size results; large sizes may impact performance"
  • choices: [Small (100x100px)|Medium (600x600px)**|Large (1200x1200px)|Very large (2000x2000px)|<user-defined>]
  • additional info: These are commonly used sizes, so using a preset will usually return results compatible with most players; however if you have a need for a size outside of those listed, set this option to "<user-defined>" and use the following size options to set the desired value. Please note that the resulting cover size will always be a reduced version the maximum size of the original cover in the database and will conform to its aspect ratio. As an example, if the original cover is 800x1000px, choosing the 2000x2000px preset will return the 800x1000px cover; and choosing 600x600px will return a proportionally correct 480x600px image.

# Size > [user-defined] > (NNNN)
The following applies when 'Size' has been set to '<user-defined>'

# 1st digit of number (N---) (drop-box)
# 2nd digit of number (-N--) (drop-box)
# 3rd digit of number (--N-) (drop-box)
# 4th digit of number (---N) (drop-box)

  • tool-tip: "Use selection boxes to set each digit of user-defined cover size (e.g. 160x160px => 0-1-6-0)"
  • choices: [0-9] **preset to 1-2-3-0
  • additional info: As the tool-tip implies, a 4-digit cover size can be manually input using each drop-box per digit; for values below '1000', leading zeros must be used. Due to the nature of how settings' values are called from the script, the best solution I could find for a size input field was splitting a number into its component digits, setting each one individually (using drop-boxes allowed a mouse-only interface), and building the final value in the script. As a side note, a 0000x0000px size cover is possible, and will be returned as such. As with the presets, the resulting cover size will conform with the maximum size and aspect ratio of the source image.

# Format (drop-box)

  • tool-tip: "Select image format to be used. Some formats may impact performance"
  • choices: [.jpg**|.png|.webp]
  • additional info: "jpg" is considered a standard image format, as it provides a reasonably good image quality relative to its file size, and provides the most compatibility with players. "png" is a lossless compression format usually for high quality images, but may compromise compatibility. "webp" is a modern image format most commonly used for images on the web due to its smaller file size, and where quality isn't very important. There is no "one" format above all; you'll find many topics on this subject in the Mp3Tag community (and others). If you are unsure, the default should be fine.

# Quality (drop-box)

  • tool-tip: "Set image quality (on supported formats). Source is responsible for quality results"
  • choices: [< default >**|20%|40%|60%|80%|100%]
  • additional info: For greater control over cover image quality (useful in large collections where file size management is important), these presets -and the following quality options- allow to fine tune the resulting cover image. Please note that quality settings only take effect on image formats that support it (on "png" format the current quality setting will be shown in "#_COVERURL", but the image's original data -and size- will remain unaltered).
    As with Format, the default setting should suffice for most use cases.

# Quality > [user-defined] > (NN)
The following applies when 'Quality' has been set to '<user-defined>'

# 1st digit of number (N-) (drop-box)
# 2nd digit of number (-N) (drop-box)

  • tool-tip: "Use selection boxes to set each digit of user-defined quality value (e.g. 7% => 0-7)"
  • choices: [0-9] **preset to 5-0
  • additional info: similarly to Size, a 0-99 value for quality can be set using each respective drop-box per digit ("100" is available via preset), with a leading "0" for numbers below 10. "0" can be set, and results will vary: "png" will remain unchanged (as previously mentioned), "jpg" normally returns an image equivalent to 80% quality, and for "webp" format the cover quality apparently equals 60%. If such level of control is unnecessary, you may leave this option in its default.
  • "Track" group

Track settings will modify text-based tags, normally written to music files, or generate new ones, according to the options set.

The following applies when 'Tag data source' has been set to its default value 'iTunes API'
# [iTunes API] > Show album/track titles (drop-box)

  • tool-tip: "(for iTunes API) Display explicit content uncensored or *'d out. Source is responsible for content results"
  • choices: [Censored|Uncensored**]
  • additional info: an iTunes API album search returns both censored and uncensored versions of their respective data in the results (normally Track titles and Album titles); and previous versions of this script already included this feature. If set to 'Censored', the script takes additional steps to verify if the censored data is complete, and will use the uncensored equivalent of any missing values to provide a complete set of results. As there is no way to validate if data content is correctly filtered, all results are presented 'as is' from the source.

# Enable TOTALCOLLECTIONTRACKS (checkbox)

  • tool-tip: "Add non-standard TOTALCOLLECTIONTRACKS tag to results"
  • choices: [enabled|disabled**]
  • additional info: Compilation collections or multiple-disc albums are commonplace; however when referring to the 'Total Tracks' value in such context, it may refer to the total number of tracks in a disc OR the sum of the total tracks of all discs (which -given the nature of current digital music services- may be more suitable than that of a physically limited 'disc'). iTunes API provides both values in its raw data; Apple Music only provides the number of total tracks in the collection, but its raw data has track information structured into groups corresponding to the equivalent physical discs, so the total tracks 'of disc' value(s) can be extrapolated from them. As most players normally only recognize one field to represent the total amount of tracks in a 'set' (regardless of the constitution of that set), I decided to have the TOTALTRACKS tag field (native to Apple) reflect the total tracks of Disc. The total number of tracks of the collection (of tracks) is produced in a custom TOTALCOLLECTIONTRACKS tag field which can be toggled using this checkbox. If you have no need for a TOTALCOLLECTIONTRACKS tag, simply keep this option unchecked; if you want both values of total tracks, TOTALTRACKS will always refer to 'Disc', and TOTALCOLLECTIONTRACKS will always refer to 'Collection'. In the need for TOTALTRACKS to refer to 'Collection', this can be achieved with further processing in Mp3Tag. As the TOTALCOLLECTIONTRACKS tag is of my design, compatibility with other players may not be possible without adjustments, if at all. Please consider your particular use case before enabling.

As a final note, please take into consideration that this script is developed and distributed as a hobby, and while I try to have it return correct data from its source(s), this may not always be the case, and therefore it should NOT be relied upon, nor should its use or results (intentional or otherwise) reflect those of the Mp3Tag software.