taglib-wasm/dist/src/utils/rating.d.ts

TagLib-Wasm is the universal tagging library for TypeScript/JavaScript platforms: Browsers, Node.js, Deno, Bun, Cloudflare Workers, and Electron apps

/**
 * Rating conversion utilities for cross-format compatibility.
 *
 * All ratings are stored internally as normalized 0.0-1.0 values.
 * These utilities convert between normalized values and format-specific
 * representations (POPM 0-255, star ratings, percentages).
 *
 * @example
 * ```typescript
 * import { RatingUtils } from 'taglib-wasm';
 *
 * // Convert from 5-star to normalized
 * const rating = RatingUtils.fromStars(4, 5);     // NormalizedRating(0.8)
 *
 * // Convert to POPM value for ID3v2
 * const popmVal = RatingUtils.toPopm(rating);      // PopmRating(196)
 *
 * // Display as percentage
 * const percent = RatingUtils.toPercent(rating);    // 80
 * ```
 */
type Brand<T, K extends string> = T & {
    readonly __brand: K;
};
/** Normalized rating value (0.0-1.0 scale). */
export type NormalizedRating = Brand<number, "NormalizedRating">;
/** POPM rating value (0-255 scale, as used in ID3v2 Popularimeter frames). */
export type PopmRating = Brand<number, "PopmRating">;
/** Create a NormalizedRating from a plain number. */
export declare function normalized(value: number): NormalizedRating;
/** Create a PopmRating from a plain number. */
export declare function popm(value: number): PopmRating;
/**
 * Convert POPM value (0-255) to normalized (0.0-1.0).
 * Precision-preserving linear conversion.
 *
 * @param value - POPM rating value (0-255)
 * @returns Normalized rating (0.0-1.0)
 */
export declare function toNormalized(value: PopmRating): NormalizedRating;
/**
 * Convert normalized (0.0-1.0) to POPM value (0-255).
 * Precision-preserving linear conversion.
 *
 * @param value - Normalized rating (0.0-1.0)
 * @returns POPM rating value (0-255)
 */
export declare function fromNormalized(value: NormalizedRating): PopmRating;
/**
 * Convert normalized rating to star value.
 *
 * @param value - Normalized rating (0.0-1.0)
 * @param maxStars - Maximum star count (default: 5)
 * @returns Star rating (0 to maxStars)
 */
export declare function toStars(value: NormalizedRating, maxStars?: number): number;
/**
 * Convert star rating to normalized value.
 *
 * @param stars - Star rating
 * @param maxStars - Maximum star count (default: 5)
 * @returns Normalized rating (0.0-1.0)
 */
export declare function fromStars(stars: number, maxStars?: number): NormalizedRating;
/**
 * Convert normalized rating to standard POPM value.
 * Uses the widely-adopted 5-star to POPM mapping.
 *
 * @param value - Normalized rating (0.0-1.0)
 * @returns POPM value (0, 1, 64, 128, 196, or 255)
 */
export declare function toPopm(value: NormalizedRating): PopmRating;
/**
 * Convert POPM value to normalized rating using standard mapping.
 * Handles the full 0-255 range by mapping to nearest star level.
 *
 * @param value - POPM rating value (0-255)
 * @returns Normalized rating (0.0, 0.2, 0.4, 0.6, 0.8, or 1.0)
 */
export declare function fromPopm(value: PopmRating): NormalizedRating;
/**
 * Convert normalized rating to percentage.
 *
 * @param value - Normalized rating (0.0-1.0)
 * @returns Percentage (0-100)
 */
export declare function toPercent(value: NormalizedRating): number;
/**
 * Convert percentage to normalized rating.
 *
 * @param percent - Percentage (0-100)
 * @returns Normalized rating (0.0-1.0)
 */
export declare function fromPercent(percent: number): NormalizedRating;
/**
 * Clamp a rating to the valid normalized range.
 *
 * @param rating - Rating value to clamp
 * @returns Rating clamped to 0.0-1.0
 */
export declare function clamp(rating: number): NormalizedRating;
/**
 * Check if a rating is valid (within 0.0-1.0 range).
 *
 * @param rating - Rating value to check
 * @returns True if rating is valid
 */
export declare function isValid(rating: number): rating is NormalizedRating;
/**
 * Namespace export for convenient grouped access.
 */
export declare const RatingUtils: {
    readonly normalized: typeof normalized;
    readonly popm: typeof popm;
    readonly toNormalized: typeof toNormalized;
    readonly fromNormalized: typeof fromNormalized;
    readonly toStars: typeof toStars;
    readonly fromStars: typeof fromStars;
    readonly toPopm: typeof toPopm;
    readonly fromPopm: typeof fromPopm;
    readonly toPercent: typeof toPercent;
    readonly fromPercent: typeof fromPercent;
    readonly clamp: typeof clamp;
    readonly isValid: typeof isValid;
    readonly POPM_STAR_VALUES: readonly [0, 1, 64, 128, 196, 255];
};
export {};
//# sourceMappingURL=rating.d.ts.map