roadamp/internal/rating/rating.go

// Package rating reads and writes ID3v2 POPM (Popularimeter) star ratings
// for MP3 files using the scale shared by Winamp and Windows Explorer:
//
//	0 = unrated
//	1 = ★☆☆☆☆  (POPM byte 1)
//	2 = ★★☆☆☆  (POPM byte 64)
//	3 = ★★★☆☆  (POPM byte 128)
//	4 = ★★★★☆  (POPM byte 196)
//	5 = ★★★★★  (POPM byte 255)
//
// The email field is set to "rating@winamp.com" (Winamp's standard identifier).
// Windows Explorer reads all POPM frames regardless of the email field.
package rating

import (
	"bytes"
	"fmt"
	"io"
	"math/big"
	"os"
	"path/filepath"
	"strings"

	id3 "github.com/bogem/id3v2/v2"
)

const emailKey = "rating@winamp.com"

// Get returns the 0–5 star rating stored in the POPM frame of path.
// Returns 0 (unrated) if the file has no POPM frame or is not an MP3.
func Get(path string) (int, error) {
	if !isMP3(path) {
		return 0, nil
	}
	tag, err := id3.Open(path, id3.Options{Parse: true, ParseFrames: []string{"POPM"}})
	if err != nil {
		return 0, fmt.Errorf("rating.Get: %w", err)
	}
	defer tag.Close()

	for _, f := range tag.GetFrames("POPM") {
		pf, ok := f.(id3.PopularimeterFrame)
		if !ok {
			continue
		}
		return popmToStars(pf.Rating), nil
	}
	return 0, nil
}

// Set writes a 0–5 star rating into the POPM frame of path.
// stars=0 removes any existing POPM frame (unrated).
//
// Strategy: bogem/id3v2's Save() creates a temp file and renames it over
// the original. The rename fails when Winamp holds the file open (Windows
// denies rename without FILE_SHARE_DELETE). Instead we:
//  1. Find where the audio data starts (parse the ID3v2 header size).
//  2. Write the new ID3 tag to an in-memory buffer via WriteTo.
//  3. Build the complete new file (tag + audio) in a temp file.
//  4. Try rename — works when the file is not currently playing.
//  5. If rename fails, stream the temp file directly into the original file
//     (requires Winamp to have opened with FILE_SHARE_WRITE, which it does).
func Set(path string, stars int) error {
	if !isMP3(path) {
		return fmt.Errorf("rating.Set: not an MP3 file: %s", filepath.Base(path))
	}
	if stars < 0 || stars > 5 {
		return fmt.Errorf("rating.Set: stars must be 0–5, got %d", stars)
	}

	// ── Step 1: locate audio data in the original file ────────────────────────
	audioStart, err := id3v2AudioStart(path)
	if err != nil {
		return fmt.Errorf("rating.Set: parse header: %w", err)
	}

	// ── Step 2: encode new tag into memory ────────────────────────────────────
	tag, err := id3.Open(path, id3.Options{Parse: true})
	if err != nil {
		return fmt.Errorf("rating.Set: open: %w", err)
	}
	tag.DeleteFrames("POPM")
	if stars > 0 {
		tag.AddFrame("POPM", id3.PopularimeterFrame{
			Email:   emailKey,
			Rating:  starsToPOPM(stars),
			Counter: big.NewInt(0),
		})
	}
	var tagBuf bytes.Buffer
	if _, err := tag.WriteTo(&tagBuf); err != nil {
		tag.Close()
		return fmt.Errorf("rating.Set: encode tag: %w", err)
	}
	tag.Close() // release read handle on original file

	// ── Step 3: write tag + audio to a temp file ──────────────────────────────
	dir := filepath.Dir(path)
	tmp, err := os.CreateTemp(dir, ".rating-*.tmp")
	if err != nil {
		return fmt.Errorf("rating.Set: create temp: %w", err)
	}
	tmpPath := tmp.Name()
	defer os.Remove(tmpPath) // clean up on any exit path

	if _, err := tmp.Write(tagBuf.Bytes()); err != nil {
		tmp.Close()
		return fmt.Errorf("rating.Set: write tag to temp: %w", err)
	}

	// Copy audio data from original file into the temp file.
	src, err := os.Open(path)
	if err != nil {
		tmp.Close()
		return fmt.Errorf("rating.Set: open src: %w", err)
	}
	if _, err := src.Seek(audioStart, io.SeekStart); err != nil {
		src.Close()
		tmp.Close()
		return fmt.Errorf("rating.Set: seek audio: %w", err)
	}
	if _, err := io.Copy(tmp, src); err != nil {
		src.Close()
		tmp.Close()
		return fmt.Errorf("rating.Set: copy audio: %w", err)
	}
	src.Close()
	if err := tmp.Close(); err != nil {
		return fmt.Errorf("rating.Set: close temp: %w", err)
	}

	// ── Step 4: try atomic rename (works when file is not open by Winamp) ─────
	if err := os.Rename(tmpPath, path); err == nil {
		return nil
	}

	// ── Step 5: rename failed — stream temp into the original file directly ───
	// This works because Winamp opens MP3s with FILE_SHARE_WRITE.
	tmpFile, err := os.Open(tmpPath)
	if err != nil {
		return fmt.Errorf("rating.Set: open temp for streaming: %w", err)
	}
	defer tmpFile.Close()

	dst, err := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, 0644)
	if err != nil {
		return fmt.Errorf("rating.Set: open dst: %w", err)
	}
	defer dst.Close()

	if _, err := io.Copy(dst, tmpFile); err != nil {
		return fmt.Errorf("rating.Set: stream to dst: %w", err)
	}
	return nil
}

// id3v2AudioStart reads the 10-byte ID3v2 header and returns the byte offset
// where audio data begins (i.e. the end of the tag). Returns 0 if no ID3v2
// tag is present.
func id3v2AudioStart(path string) (int64, error) {
	f, err := os.Open(path)
	if err != nil {
		return 0, err
	}
	defer f.Close()

	var hdr [10]byte
	if _, err := io.ReadFull(f, hdr[:]); err != nil {
		return 0, nil // file too short — no tag
	}
	if string(hdr[:3]) != "ID3" {
		return 0, nil // no ID3v2 tag
	}
	// Bytes 6–9 are a synchsafe integer (7 bits per byte).
	size := int64(hdr[6])<<21 | int64(hdr[7])<<14 | int64(hdr[8])<<7 | int64(hdr[9])
	return 10 + size, nil
}

func isMP3(path string) bool {
	return strings.EqualFold(filepath.Ext(path), ".mp3")
}

// popmToStars maps a raw POPM byte to a 0–5 star rating using the
// Windows Explorer / Winamp read ranges.
func popmToStars(r uint8) int {
	switch {
	case r == 0:
		return 0
	case r < 32:
		return 1
	case r < 96:
		return 2
	case r < 160:
		return 3
	case r < 224:
		return 4
	default:
		return 5
	}
}

// starsToPOPM returns the canonical POPM byte for a given star count.
func starsToPOPM(stars int) uint8 {
	return [6]uint8{0, 1, 64, 128, 196, 255}[stars]
}