# 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.
> iTunes
>   This mapping has values 0 - 100. It is the format internally used by iTunes. When an iTunes 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 iTunes 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 iTunes, the internal format is always translated to the iTunes mapping. When importing ratings from iTunes, the iTunes values are always translated to Yate's internal format. As Yate translates values where appropriate when reading and writing files, your ratings in iTunes are insulated from the different mappings used with various file types.

If you are using iTunes 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 if the effective number of stars displayed for the value being translated is changing. Reseting the values in iTunes only requires doing an Export to iTunes. Remember that Yate automatically translates its internal format to the iTunes format when exporting to iTunes.

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