Application icon

How Ratings Work

The ID3 specification supports rating values of 0 - 255. Yate internally maintains rating values in the same range. Yate divides the values into segments where each value within a segment is associated with the same number of stars. When first installed and unless changed, Yate maintains the following segments:

no stars
0-8
9-49
★★
50-113
★★★
114-167
★★★★
168-218
★★★★★
219-255

All rating values in files are interpreted in one of four ways called mappings:

Direct
This mapping implies that the set of values stored in the file is in the range of 0 - 5. When a Direct mapping is being used, Yate automatically translates the values to its internal format when reading the files. When writing the files, Yate translates its internal format to the Direct mapping.

Apple
This mapping has values 0 - 100. It is the format internally used by iTunes/Music/TV. When an Apple mapping is being used, Yate automatically translates the values to its internal format when reading the files. When writing the files, Yate translates its internal format to the Apple mapping. This mapping is always used with m4a and mp4 files.

Full
This mapping has values 0 - 255. It is the most commonly used format with ID3 based formats. When a Full mapping is being used, no translation occurs when reading or writing the files.

Direct*2
This mapping implies that the set of values stored in the file is in the range of 0 - 10. When a Direct*2 mapping is being used, Yate automatically translates the values to its internal format when reading the files. When writing the files, Yate translates its internal format to the Direct*2 mapping. We've only ever seen this format used by JRiver Media Center when writing MPEG-4 values.

While Yate always maintains ratings as a value in the range of 0 - 255, it has to be able to map the values to a five star visualization for the rating field's display. It also has to map a user specified star rating to its internal representation. The number associated within a segment is called the write value. Yate's default write values are the lowest numbers in each segment. ie. 0, 9, 50, 114, 168, 219.

When exporting ratings to an Apple app, the internal format is always translated to the Apple mapping. When importing ratings from an Apple app, the Apple values are always translated to Yate's internal format. As Yate translates values where appropriate when reading and writing files, your ratings in Apple apps are insulated from the different mappings used with various file types.

If you are using iTunes/Music/TV and Yate the ratings display will always be consistant with Yate's defaults. If however, you are using a different media player it is possible that the player uses an entirely different allotment of value segments than those defaulted by Yate. For this reason, Yate allows you to change its default Full interpretation to any association of the 256 values to five stars. It also lets you pick the write values you would like to use. This custom mapping can be specified in the Audio section of the application preferences.

If you are changing the default rating mapping or if you want to convert rating values created in other taggers, you can use the Translate Ratings action statement. This statement, when used with the proper workflow, lets you convert a stored encoding to a different encoding. Note that after translating ratings you only have to reset your ratings in iTunes/Music/TV if the effective number of stars displayed for the value being translated is changing. Reseting the values in an Apple app only requires doing an Export to Apple App. Remember that Yate automatically translates its internal format to the Apple format when exporting.

What internal Full mapping is used can be totally transparent to the actions you write. You can use the \R escape sequence to get a rating value as an absolute number of stars. Also the Set action function can be used to write a rating as an absolute number of stars or as a full value.


Additional Information:


Translate Ratings action statement

Notes on Translating Ratings