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

TagLib for TypeScript platforms: Deno, Node.js, Bun, Electron, browsers, and Cloudflare Workers

/**
 * 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 normalized = RatingUtils.fromStars(4, 5);  // 0.8
 *
 * // Convert to POPM value for ID3v2
 * const popm = RatingUtils.toPopm(0.8);  // 196
 *
 * // Display as percentage
 * const percent = RatingUtils.toPercent(0.8);  // 80
 * ```
 */
/**
 * Convert POPM value (0-255) to normalized (0.0-1.0).
 * Precision-preserving linear conversion.
 *
 * @param popm - POPM rating value (0-255)
 * @returns Normalized rating (0.0-1.0)
 */
export declare function toNormalized(popm: number): number;
/**
 * Convert normalized (0.0-1.0) to POPM value (0-255).
 * Precision-preserving linear conversion.
 *
 * @param normalized - Normalized rating (0.0-1.0)
 * @returns POPM rating value (0-255)
 */
export declare function fromNormalized(normalized: number): number;
/**
 * Convert normalized rating to star value.
 *
 * @param normalized - Normalized rating (0.0-1.0)
 * @param maxStars - Maximum star count (default: 5)
 * @returns Star rating (0 to maxStars)
 */
export declare function toStars(normalized: number, 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): number;
/**
 * Convert normalized rating to standard POPM value.
 * Uses the widely-adopted 5-star to POPM mapping.
 *
 * @param normalized - Normalized rating (0.0-1.0)
 * @returns POPM value (0, 1, 64, 128, 196, or 255)
 */
export declare function toPopm(normalized: number): number;
/**
 * Convert POPM value to normalized rating using standard mapping.
 * Handles the full 0-255 range by mapping to nearest star level.
 *
 * @param popm - 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(popm: number): number;
/**
 * Convert normalized rating to percentage.
 *
 * @param normalized - Normalized rating (0.0-1.0)
 * @returns Percentage (0-100)
 */
export declare function toPercent(normalized: number): number;
/**
 * Convert percentage to normalized rating.
 *
 * @param percent - Percentage (0-100)
 * @returns Normalized rating (0.0-1.0)
 */
export declare function fromPercent(percent: number): number;
/**
 * 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): number;
/**
 * 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): boolean;
/**
 * Namespace export for convenient grouped access.
 */
export declare const RatingUtils: {
    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];
};
//# sourceMappingURL=rating.d.ts.map