claude: fold in old sow-tools

internal/music/config.go

@@ -0,0 +1,47 @@
+package music
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+type DatasetConfig struct {
+	Source      string `json:"source" yaml:"source"`
+	Prefix      string `json:"prefix,omitempty" yaml:"prefix,omitempty"`
+	StageRoot   string `json:"stage_root,omitempty" yaml:"stage_root,omitempty"`
+	CreditsRoot string `json:"credits_root,omitempty" yaml:"credits_root,omitempty"`
+}
+
+type DefaultsConfig struct {
+	StageRoot      string `json:"stage_root,omitempty" yaml:"stage_root,omitempty"`
+	CreditsRoot    string `json:"credits_root,omitempty" yaml:"credits_root,omitempty"`
+	CreditsOverlay string `json:"credits_overlay,omitempty" yaml:"credits_overlay,omitempty"`
+	MaxStemLength  *int   `json:"max_stem_length,omitempty" yaml:"max_stem_length,omitempty"`
+}
+
+func ValidateDatasetSource(field, source string) error {
+	trimmed := strings.TrimSpace(source)
+	if trimmed == "" {
+		return fmt.Errorf("%s.source is required", field)
+	}
+	if strings.Contains(trimmed, "\x00") {
+		return fmt.Errorf("%s.source must not contain NUL bytes", field)
+	}
+	clean := filepath.Clean(filepath.FromSlash(trimmed))
+	if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
+		return fmt.Errorf("%s.source must not escape project root", field)
+	}
+	return nil
+}
+
+func ValidateDatasetID(id string) error {
+	trimmed := strings.TrimSpace(id)
+	if trimmed == "" {
+		return fmt.Errorf("dataset id must not be empty")
+	}
+	if strings.Contains(trimmed, "/") || strings.Contains(trimmed, "\\") {
+		return fmt.Errorf("dataset id %q must not contain path separators", trimmed)
+	}
+	return nil
+}

internal/music/credits.go

@@ -0,0 +1,292 @@
+package music
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func ParseCreditsOverlay(path string) (CreditsOverlay, error) {
+	entries, err := ParseCreditsMarkdown(path)
+	if err != nil {
+		return CreditsOverlay{}, err
+	}
+	overlay := CreditsOverlay{
+		ByOriginal: make(map[string]CreditsEntry),
+		ByOutput:   make(map[string]CreditsEntry),
+		Entries:    entries,
+	}
+	for _, entry := range entries {
+		if entry.OriginalFile != "" {
+			key := strings.ToLower(strings.TrimSpace(entry.OriginalFile))
+			if _, exists := overlay.ByOriginal[key]; exists {
+				return CreditsOverlay{}, fmt.Errorf("duplicate manual credits row for original file %s", entry.OriginalFile)
+			}
+			overlay.ByOriginal[key] = entry
+		}
+		if entry.OutputFile != "" {
+			key := strings.ToLower(strings.TrimSpace(entry.OutputFile))
+			if _, exists := overlay.ByOutput[key]; exists {
+				return CreditsOverlay{}, fmt.Errorf("duplicate manual credits row for output file %s", entry.OutputFile)
+			}
+			overlay.ByOutput[key] = entry
+		}
+	}
+	return overlay, nil
+}
+
+func (o CreditsOverlay) Match(originalFile, outputFile string) *CreditsEntry {
+	if entry, ok := o.ByOutput[strings.ToLower(strings.TrimSpace(outputFile))]; ok {
+		entryCopy := entry
+		return &entryCopy
+	}
+	if entry, ok := o.ByOriginal[strings.ToLower(strings.TrimSpace(originalFile))]; ok {
+		entryCopy := entry
+		return &entryCopy
+	}
+	return nil
+}
+
+func ValidateOverlayEntries(dir string, overlay CreditsOverlay, generated []CreditsEntry) error {
+	if len(overlay.Entries) == 0 {
+		return nil
+	}
+	validOriginal := make(map[string]struct{}, len(generated))
+	validOutput := make(map[string]struct{}, len(generated))
+	for _, entry := range generated {
+		validOriginal[strings.ToLower(entry.OriginalFile)] = struct{}{}
+		validOutput[strings.ToLower(entry.OutputFile)] = struct{}{}
+	}
+	for _, entry := range overlay.Entries {
+		if entry.OriginalFile != "" {
+			if _, ok := validOriginal[strings.ToLower(entry.OriginalFile)]; !ok {
+				return fmt.Errorf("manual credits entry in %s references unknown original file %s", dir, entry.OriginalFile)
+			}
+		}
+		if entry.OutputFile != "" {
+			if _, ok := validOutput[strings.ToLower(entry.OutputFile)]; !ok {
+				return fmt.Errorf("manual credits entry in %s references unknown output file %s", dir, entry.OutputFile)
+			}
+		}
+	}
+	return nil
+}
+
+func ParseCreditsMarkdown(path string) ([]CreditsEntry, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	lines := strings.Split(strings.ReplaceAll(string(raw), "\r\n", "\n"), "\n")
+	header := []string(nil)
+	entries := make([]CreditsEntry, 0)
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if !strings.HasPrefix(line, "|") {
+			continue
+		}
+		cells := ParseMarkdownTableRow(line)
+		if len(cells) == 0 {
+			continue
+		}
+		if header == nil {
+			header = make([]string, len(cells))
+			for i, cell := range cells {
+				header[i] = NormalizeCreditsHeader(cell)
+			}
+			continue
+		}
+		if IsMarkdownSeparatorRow(cells) {
+			continue
+		}
+		entry := CreditsEntry{}
+		for i, key := range header {
+			if i >= len(cells) {
+				continue
+			}
+			value := CleanCreditsCell(cells[i])
+			switch key {
+			case "artist":
+				entry.Artist = value
+			case "title":
+				entry.Title = value
+			case "output_file":
+				entry.OutputFile = value
+			case "original_file":
+				entry.OriginalFile = value
+			case "album":
+				entry.Album = value
+			case "date":
+				entry.Date = value
+			case "rights":
+				entry.Rights = value
+			case "notes":
+				entry.Notes = value
+			}
+		}
+		if entry.Artist == "" && entry.Title == "" && entry.OutputFile == "" && entry.OriginalFile == "" {
+			continue
+		}
+		entries = append(entries, entry)
+	}
+	return entries, nil
+}
+
+func ParseMarkdownTableRow(line string) []string {
+	trimmed := strings.TrimSpace(line)
+	trimmed = strings.TrimPrefix(trimmed, "|")
+	trimmed = strings.TrimSuffix(trimmed, "|")
+	parts := strings.Split(trimmed, "|")
+	cells := make([]string, 0, len(parts))
+	for _, part := range parts {
+		cells = append(cells, strings.TrimSpace(strings.ReplaceAll(part, `\|`, "|")))
+	}
+	return cells
+}
+
+func IsMarkdownSeparatorRow(cells []string) bool {
+	if len(cells) == 0 {
+		return false
+	}
+	for _, cell := range cells {
+		cell = strings.TrimSpace(cell)
+		cell = strings.ReplaceAll(cell, "-", "")
+		cell = strings.ReplaceAll(cell, ":", "")
+		if cell != "" {
+			return false
+		}
+	}
+	return true
+}
+
+func NormalizeCreditsHeader(value string) string {
+	switch strings.ToLower(CleanCreditsCell(value)) {
+	case "artist":
+		return "artist"
+	case "title":
+		return "title"
+	case "output file":
+		return "output_file"
+	case "original file":
+		return "original_file"
+	case "album":
+		return "album"
+	case "date":
+		return "date"
+	case "license / copyright":
+		return "rights"
+	case "notes":
+		return "notes"
+	default:
+		return ""
+	}
+}
+
+func CleanCreditsCell(value string) string {
+	value = strings.TrimSpace(value)
+	value = strings.Trim(value, "`")
+	value = strings.ReplaceAll(value, "<br>", "\n")
+	return strings.TrimSpace(value)
+}
+
+func RenderCreditsMarkdown(entries []CreditsEntry) string {
+	var builder strings.Builder
+	builder.WriteString(CreditsHeader)
+	for _, entry := range entries {
+		builder.WriteString("| ")
+		builder.WriteString(EscapeMarkdownCell(entry.Artist))
+		builder.WriteString(" | ")
+		builder.WriteString(EscapeMarkdownCell(entry.Title))
+		builder.WriteString(" | ")
+		builder.WriteString(EscapeMarkdownCell(WrapCodeCell(entry.OutputFile)))
+		builder.WriteString(" | ")
+		builder.WriteString(EscapeMarkdownCell(WrapCodeCell(entry.OriginalFile)))
+		builder.WriteString(" | ")
+		builder.WriteString(EscapeMarkdownCell(entry.Album))
+		builder.WriteString(" | ")
+		builder.WriteString(EscapeMarkdownCell(entry.Date))
+		builder.WriteString(" | ")
+		builder.WriteString(EscapeMarkdownCell(entry.Rights))
+		builder.WriteString(" | ")
+		builder.WriteString(EscapeMarkdownCell(entry.Notes))
+		builder.WriteString(" |\n")
+	}
+	return builder.String()
+}
+
+func WrapCodeCell(value string) string {
+	if strings.TrimSpace(value) == "" {
+		return ""
+	}
+	return "`" + value + "`"
+}
+
+func EscapeMarkdownCell(value string) string {
+	value = strings.ReplaceAll(value, `\`, `\\`)
+	value = strings.ReplaceAll(value, "|", `\|`)
+	value = strings.ReplaceAll(value, "\n", "<br>")
+	return value
+}
+
+func ApplyCreditsOverlay(entry *CreditsEntry, overlay *CreditsEntry) {
+	if overlay == nil {
+		return
+	}
+	entry.Artist = FirstNonEmpty(overlay.Artist, entry.Artist)
+	entry.Title = FirstNonEmpty(overlay.Title, entry.Title)
+	entry.Album = FirstNonEmpty(overlay.Album, entry.Album)
+	entry.Date = FirstNonEmpty(overlay.Date, entry.Date)
+	entry.Rights = FirstNonEmpty(overlay.Rights, entry.Rights)
+	entry.Notes = FirstNonEmpty(overlay.Notes, entry.Notes)
+}
+
+func SyncGeneratedCreditsArtifacts(root string, desiredFiles map[string][]byte) (int, error) {
+	changedFiles := 0
+	existingFiles := make(map[string]struct{})
+	if err := filepath.WalkDir(root, func(path string, d os.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			if os.IsNotExist(walkErr) {
+				return nil
+			}
+			return walkErr
+		}
+		if d.IsDir() {
+			return nil
+		}
+		existingFiles[path] = struct{}{}
+		return nil
+	}); err != nil {
+		return 0, fmt.Errorf("scan credits dir: %w", err)
+	}
+
+	for path, content := range desiredFiles {
+		current, err := os.ReadFile(path)
+		if err != nil && !os.IsNotExist(err) {
+			return 0, fmt.Errorf("read credits artifact %s: %w", path, err)
+		}
+		if err == nil && string(current) == string(content) {
+			delete(existingFiles, path)
+			continue
+		}
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			return 0, fmt.Errorf("create generated credits dir: %w", err)
+		}
+		if err := os.WriteFile(path, content, 0o644); err != nil {
+			return 0, fmt.Errorf("write credits artifact %s: %w", path, err)
+		}
+		changedFiles++
+		delete(existingFiles, path)
+	}
+
+	for path := range existingFiles {
+		if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+			return 0, fmt.Errorf("remove stale credits artifact %s: %w", path, err)
+		}
+		changedFiles++
+	}
+	return changedFiles, nil
+}

internal/music/metadata.go

@@ -0,0 +1,62 @@
+package music
+
+import (
+	"encoding/json"
+	"fmt"
+	"os/exec"
+	"strings"
+)
+
+func ProbeMetadata(ffprobePath, sourcePath string) (Metadata, error) {
+	cmd := exec.Command(ffprobePath, "-v", "quiet", "-print_format", "json", "-show_format", sourcePath)
+	output, err := cmd.Output()
+	if err != nil {
+		return Metadata{}, err
+	}
+	var payload struct {
+		Format struct {
+			Tags map[string]string `json:"tags"`
+		} `json:"format"`
+	}
+	if err := json.Unmarshal(output, &payload); err != nil {
+		return Metadata{}, err
+	}
+	tags := make(map[string]string, len(payload.Format.Tags))
+	for key, value := range payload.Format.Tags {
+		tags[strings.ToLower(strings.TrimSpace(key))] = strings.TrimSpace(value)
+	}
+	return Metadata{
+		Title:     FirstNonEmpty(tags["title"]),
+		Artist:    FirstNonEmpty(tags["artist"], tags["album_artist"], tags["composer"]),
+		Album:     FirstNonEmpty(tags["album"]),
+		Date:      FirstNonEmpty(tags["date"], tags["year"]),
+		Comment:   FirstNonEmpty(tags["comment"], tags["description"]),
+		Copyright: FirstNonEmpty(tags["copyright"]),
+		License:   FirstNonEmpty(tags["license"], tags["license_url"]),
+	}, nil
+}
+
+func ConvertSource(ffmpegPath, sourcePath, outputPath string) error {
+	cmd := exec.Command(
+		ffmpegPath, "-y",
+		"-i", sourcePath,
+		"-vn",
+		"-map_metadata", "-1",
+		"-ar", "44100",
+		"-ac", "2",
+		"-b:a", "192k",
+		"-codec:a", "libmp3lame",
+		"-write_xing", "0",
+		"-f", "mp3",
+		outputPath,
+	)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		message := strings.TrimSpace(string(output))
+		if message == "" {
+			message = err.Error()
+		}
+		return fmt.Errorf("%s", message)
+	}
+	return nil
+}

internal/music/music.go

@@ -0,0 +1,226 @@
+package music
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+const (
+	MaxStemLen    = 16
+	CreditsHeader = "# NWN Music Pack Credits\n\nOriginal rights remain with the respective composers and licensors.\n\n## Processed Files\n\n| Artist | Title | Output File | Original File | Album | Date | License / Copyright | Notes |\n|---|---|---|---|---|---|---|---|\n"
+)
+
+var (
+	defaultConvertExtensions = []string{
+		".flac",
+		".m4a",
+		".mp3",
+		".ogg",
+		".wav",
+	}
+	ConvertExtensions = map[string]struct{}{
+		".flac": {},
+		".m4a":  {},
+		".mp3":  {},
+		".ogg":  {},
+		".wav":  {},
+	}
+	PassthroughExtensions = map[string]struct{}{
+		".bmu": {},
+		".wav": {},
+	}
+	DropWords = map[string]struct{}{
+		"mp3": {}, "wav": {}, "flac": {}, "ogg": {}, "m4a": {},
+		"music": {}, "track": {}, "audio": {}, "song": {}, "soundtrack": {},
+		"final": {}, "version": {}, "ver": {}, "v": {}, "mix": {}, "master": {}, "remaster": {},
+		"free": {}, "royalty": {}, "copyright": {}, "background": {}, "bgm": {},
+		"loop": {}, "loops": {}, "loopable": {}, "seamless": {},
+		"official": {}, "download": {}, "preview": {},
+		"the": {}, "a": {}, "an": {}, "and": {}, "of": {}, "to": {}, "in": {}, "for": {}, "with": {}, "by": {},
+	}
+	BracketRE = regexp.MustCompile(`\[[^\]]*\]|\([^)]*\)|\{[^}]*\}`)
+	SplitRE   = regexp.MustCompile(`[^A-Za-z0-9]+`)
+	YearRE    = regexp.MustCompile(`^\d{4,}$`)
+	VowelRE   = regexp.MustCompile(`[aeiou]`)
+)
+
+func DefaultConvertExtensions() []string {
+	return append([]string(nil), defaultConvertExtensions...)
+}
+
+type Metadata struct {
+	Title     string
+	Artist    string
+	Album     string
+	Date      string
+	Rights    string
+	Notes     string
+	Comment   string
+	Copyright string
+	License   string
+}
+
+type CreditsEntry struct {
+	Artist       string `json:"artist"`
+	Title        string `json:"title"`
+	OutputFile   string `json:"output_file"`
+	OriginalFile string `json:"original_file"`
+	Album        string `json:"album"`
+	Date         string `json:"date"`
+	Rights       string `json:"rights"`
+	Notes        string `json:"notes"`
+}
+
+type CreditsSource struct {
+	Path    string         `json:"path"`
+	Kind    string         `json:"kind"`
+	Entries []CreditsEntry `json:"entries"`
+}
+
+type CreditsInventory struct {
+	Sources []CreditsSource `json:"sources"`
+}
+
+type CreditsOverlay struct {
+	ByOriginal map[string]CreditsEntry
+	ByOutput   map[string]CreditsEntry
+	Entries    []CreditsEntry
+}
+
+func ResolveFFmpeg() (string, error) {
+	return ResolveFFmpegWithConfig("")
+}
+
+func ResolveFFmpegWithConfig(configuredPath string) (string, error) {
+	if configured := strings.TrimSpace(configuredPath); configured != "" {
+		return configured, nil
+	}
+	if configured := strings.TrimSpace(os.Getenv("SOW_FFMPEG")); configured != "" {
+		return configured, nil
+	}
+	path, err := exec.LookPath("ffmpeg")
+	if err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+func ResolveFFprobe() (string, error) {
+	return ResolveFFprobeWithConfig("")
+}
+
+func ResolveFFprobeWithConfig(configuredPath string) (string, error) {
+	if configured := strings.TrimSpace(configuredPath); configured != "" {
+		return configured, nil
+	}
+	if configured := strings.TrimSpace(os.Getenv("SOW_FFPROBE")); configured != "" {
+		return configured, nil
+	}
+	path, err := exec.LookPath("ffprobe")
+	if err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+func IsMusicAssetPath(rel string) bool {
+	rel = filepath.ToSlash(strings.TrimSpace(rel))
+	return rel == "envi/music" || strings.HasPrefix(rel, "envi/music/")
+}
+
+func PathIsUnder(root, rel string) bool {
+	root = TrimSlashes(filepath.ToSlash(root))
+	rel = TrimSlashes(filepath.ToSlash(rel))
+	if root == "" || rel == "" {
+		return false
+	}
+	return rel == root || strings.HasPrefix(rel, root+"/")
+}
+
+func PrefixForDir(prefixes map[string]string, dir string) string {
+	dir = TrimSlashes(filepath.ToSlash(dir))
+	bestPrefix := ""
+	bestLen := -1
+	keys := make([]string, 0, len(prefixes))
+	for key := range prefixes {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		value := prefixes[key]
+		normalizedKey := TrimSlashes(filepath.ToSlash(key))
+		if normalizedKey == "" {
+			continue
+		}
+		if dir != normalizedKey && !strings.HasPrefix(dir, normalizedKey+"/") {
+			continue
+		}
+		if len(normalizedKey) > bestLen {
+			bestLen = len(normalizedKey)
+			bestPrefix = SanitizePrefix(value)
+		}
+	}
+	return bestPrefix
+}
+
+func SanitizePrefix(prefix string) string {
+	prefix = strings.ToLower(strings.TrimSpace(prefix))
+	var builder strings.Builder
+	for _, r := range prefix {
+		switch {
+		case r >= 'a' && r <= 'z':
+			builder.WriteRune(r)
+		case r >= '0' && r <= '9':
+			builder.WriteRune(r)
+		case r == '_':
+			builder.WriteRune(r)
+		}
+	}
+	result := builder.String()
+	if strings.TrimSpace(prefix) != "" && strings.HasSuffix(strings.TrimSpace(prefix), "_") && !strings.HasSuffix(result, "_") {
+		result += "_"
+	}
+	return result
+}
+
+func TrimSlashes(value string) string {
+	return strings.Trim(strings.TrimSpace(value), "/")
+}
+
+func Min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func Max(a, b int) int {
+	if a > b {
+		return a
+	}
+	return b
+}
+
+func FirstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return strings.TrimSpace(value)
+		}
+	}
+	return ""
+}
+
+func JoinNonEmpty(sep string, values ...string) string {
+	parts := make([]string, 0, len(values))
+	for _, value := range values {
+		value = strings.TrimSpace(value)
+		if value != "" {
+			parts = append(parts, value)
+		}
+	}
+	return strings.Join(parts, sep)
+}

internal/music/music_test.go

@@ -0,0 +1,404 @@
+package music
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestUniqueNameHandlesShortStemCollisions(t *testing.T) {
+	used := map[string]struct{}{
+		"mus_wg_mystc": {},
+	}
+
+	got := UniqueName("mus_wg_mystc", used)
+	if got != "mus_wg_mystc_1" {
+		t.Fatalf("unexpected collision result: got %q want %q", got, "mus_wg_mystc_1")
+	}
+}
+
+func TestUniqueNameNoCollision(t *testing.T) {
+	used := map[string]struct{}{}
+	got := UniqueName("new_stem", used)
+	if got != "new_stem" {
+		t.Fatalf("expected 'new_stem', got %q", got)
+	}
+}
+
+func TestUniqueNameMultipleCollisions(t *testing.T) {
+	used := map[string]struct{}{
+		"stem":   {},
+		"stem_1": {},
+		"stem_2": {},
+	}
+	got := UniqueName("stem", used)
+	if got != "stem_3" {
+		t.Fatalf("expected 'stem_3', got %q", got)
+	}
+}
+
+func TestGenerateStem(t *testing.T) {
+	used := map[string]struct{}{
+		"existing": {},
+	}
+	stem, err := GenerateStem("My Cool Track.mp3", "mus_", used)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if stem == "" {
+		t.Fatal("expected non-empty stem")
+	}
+	if len(stem) > MaxStemLen {
+		t.Fatalf("stem %q exceeds max length %d", stem, MaxStemLen)
+	}
+	if _, exists := used[stem]; !exists {
+		t.Fatal("expected stem to be registered in used set")
+	}
+}
+
+func TestGenerateStemPrefixTooLong(t *testing.T) {
+	_, err := GenerateStem("test.mp3", "this_prefix_is_way_too_long_for_stem_", nil)
+	if err == nil {
+		t.Fatal("expected error for too-long prefix")
+	}
+}
+
+func TestSlugWords(t *testing.T) {
+	words := SlugWords("My Cool Music Track (Official) [HD]")
+	if len(words) == 0 {
+		t.Fatal("expected non-empty words")
+	}
+}
+
+func TestSlugWordsStripsBrackets(t *testing.T) {
+	words := SlugWords("Song [Explicit] (Remix)")
+	for _, w := range words {
+		if w == "explicit" || w == "remix" {
+			t.Fatalf("bracket content should be removed, got word %q", w)
+		}
+	}
+}
+
+func TestSanitizePrefix(t *testing.T) {
+	if got := SanitizePrefix("Mus_WG_"); got != "mus_wg_" {
+		t.Fatalf("unexpected prefix: %q", got)
+	}
+	if got := SanitizePrefix("  Test  "); got != "test" {
+		t.Fatalf("unexpected prefix: %q", got)
+	}
+	if got := SanitizePrefix(""); got != "" {
+		t.Fatalf("expected empty prefix, got %q", got)
+	}
+}
+
+func TestReserveName(t *testing.T) {
+	used := map[string]struct{}{}
+	if err := ReserveName("testname", used); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, exists := used["testname"]; !exists {
+		t.Fatal("expected name to be reserved")
+	}
+	if err := ReserveName("testname", used); err == nil {
+		t.Fatal("expected error for duplicate name")
+	}
+}
+
+func TestValidateManualOutputFile(t *testing.T) {
+	if err := ValidateManualOutputFile("test.bmu"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if err := ValidateManualOutputFile("test.txt"); err == nil {
+		t.Fatal("expected error for non-bmu extension")
+	}
+	if err := ValidateManualOutputFile(".bmu"); err == nil {
+		t.Fatal("expected error for empty stem")
+	}
+}
+
+func TestParseCreditsMarkdownMissingFile(t *testing.T) {
+	entries, err := ParseCreditsMarkdown("nonexistent.md")
+	if err != nil {
+		t.Fatalf("unexpected error for missing file: %v", err)
+	}
+	if entries != nil {
+		t.Fatalf("expected nil entries for missing file, got %v", entries)
+	}
+}
+
+func TestParseCreditsMarkdownRealContent(t *testing.T) {
+	content := "# Header\n\n| Artist | Title | Output File | Original File | Album | Date | License / Copyright | Notes |\n|---|---|---|---|---|---|---|---|\n| Test Artist | Test Title | `output.bmu` | `original.mp3` | Test Album | 2024 | MIT | test |\n"
+	path := filepath.Join(t.TempDir(), "CREDITS.md")
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write test credits: %v", err)
+	}
+
+	entries, err := ParseCreditsMarkdown(path)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(entries))
+	}
+	if entries[0].Artist != "Test Artist" {
+		t.Fatalf("expected 'Test Artist', got %q", entries[0].Artist)
+	}
+	if entries[0].Title != "Test Title" {
+		t.Fatalf("expected 'Test Title', got %q", entries[0].Title)
+	}
+	if entries[0].OutputFile != "output.bmu" {
+		t.Fatalf("expected 'output.bmu', got %q", entries[0].OutputFile)
+	}
+}
+
+func TestRenderCreditsMarkdown(t *testing.T) {
+	entries := []CreditsEntry{
+		{
+			Artist:       "Test Artist",
+			Title:        "Test Title",
+			OutputFile:   "output.bmu",
+			OriginalFile: "original.mp3",
+			Album:        "Test Album",
+			Date:         "2024",
+			Rights:       "MIT",
+			Notes:        "test note",
+		},
+	}
+
+	result := RenderCreditsMarkdown(entries)
+	if !strings.Contains(result, "Test Artist") {
+		t.Fatal("expected rendered output to contain artist")
+	}
+	if !strings.Contains(result, "output.bmu") {
+		t.Fatal("expected rendered output to contain output file")
+	}
+}
+
+func TestParseCreditsOverlay(t *testing.T) {
+	content := "# Header\n\n| Artist | Title | Output File | Original File |\n|---|---|---|---|\n| Overlay Artist | Ovr Title | `override.bmu` | `original.mp3` |\n"
+	path := filepath.Join(t.TempDir(), "CREDITS.md")
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write test overlay: %v", err)
+	}
+
+	overlay, err := ParseCreditsOverlay(path)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(overlay.Entries) != 1 {
+		t.Fatalf("expected 1 overlay entry, got %d", len(overlay.Entries))
+	}
+
+	matched := overlay.Match("original.mp3", "")
+	if matched == nil {
+		t.Fatal("expected overlay match by original file")
+	}
+	if matched.Artist != "Overlay Artist" {
+		t.Fatalf("expected 'Overlay Artist', got %q", matched.Artist)
+	}
+}
+
+func TestApplyCreditsOverlay(t *testing.T) {
+	entry := &CreditsEntry{
+		Artist: "Original Artist",
+		Title:  "Original Title",
+	}
+	overlay := &CreditsEntry{
+		Artist: "Overlay Artist",
+	}
+
+	ApplyCreditsOverlay(entry, overlay)
+	if entry.Artist != "Overlay Artist" {
+		t.Fatalf("expected 'Overlay Artist', got %q", entry.Artist)
+	}
+	if entry.Title != "Original Title" {
+		t.Fatalf("expected 'Original Title' preserved, got %q", entry.Title)
+	}
+
+	ApplyCreditsOverlay(entry, nil)
+	if entry.Artist != "Overlay Artist" {
+		t.Fatalf("expected nil overlay to be no-op, got %q", entry.Artist)
+	}
+}
+
+func TestValidateOverlayEntries(t *testing.T) {
+	generated := []CreditsEntry{
+		{OriginalFile: "track1.mp3", OutputFile: "track1.bmu"},
+	}
+	overlay := CreditsOverlay{
+		Entries: []CreditsEntry{
+			{OriginalFile: "track1.mp3"},
+		},
+	}
+	if err := ValidateOverlayEntries("test", overlay, generated); err != nil {
+		t.Fatalf("unexpected validation error: %v", err)
+	}
+
+	badOverlay := CreditsOverlay{
+		Entries: []CreditsEntry{
+			{OriginalFile: "nonexistent.mp3"},
+		},
+	}
+	if err := ValidateOverlayEntries("test", badOverlay, generated); err == nil {
+		t.Fatal("expected validation error for unknown original file")
+	}
+}
+
+func TestIsMusicAssetPath(t *testing.T) {
+	if !IsMusicAssetPath("envi/music") {
+		t.Fatal("expected 'envi/music' to be music path")
+	}
+	if !IsMusicAssetPath("envi/music/westgate") {
+		t.Fatal("expected 'envi/music/westgate' to be music path")
+	}
+	if IsMusicAssetPath("envi/textures") {
+		t.Fatal("expected 'envi/textures' not to be music path")
+	}
+	if IsMusicAssetPath("") {
+		t.Fatal("expected empty string not to be music path")
+	}
+}
+
+func TestFirstNonEmpty(t *testing.T) {
+	if got := FirstNonEmpty("", "hello", "world"); got != "hello" {
+		t.Fatalf("expected 'hello', got %q", got)
+	}
+	if got := FirstNonEmpty("", "", ""); got != "" {
+		t.Fatalf("expected empty, got %q", got)
+	}
+	if got := FirstNonEmpty("first"); got != "first" {
+		t.Fatalf("expected 'first', got %q", got)
+	}
+}
+
+func TestJoinNonEmpty(t *testing.T) {
+	if got := JoinNonEmpty(", ", "a", "", "b"); got != "a, b" {
+		t.Fatalf("expected 'a, b', got %q", got)
+	}
+	if got := JoinNonEmpty(", "); got != "" {
+		t.Fatalf("expected empty, got %q", got)
+	}
+}
+
+func TestTrimSlashes(t *testing.T) {
+	if got := TrimSlashes("/foo/bar/"); got != "foo/bar" {
+		t.Fatalf("expected 'foo/bar', got %q", got)
+	}
+	if got := TrimSlashes("///"); got != "" {
+		t.Fatalf("expected empty, got %q", got)
+	}
+}
+
+func TestEscapeMarkdownCell(t *testing.T) {
+	result := EscapeMarkdownCell("a|b\nc")
+	if !strings.Contains(result, `\|`) {
+		t.Fatal("expected pipe to be escaped")
+	}
+	if !strings.Contains(result, "<br>") {
+		t.Fatal("expected newline to be replaced with <br>")
+	}
+}
+
+func TestWrapCodeCell(t *testing.T) {
+	if got := WrapCodeCell("test.bmu"); got != "`test.bmu`" {
+		t.Fatalf("expected '`test.bmu`', got %q", got)
+	}
+	if got := WrapCodeCell(""); got != "" {
+		t.Fatalf("expected empty string, got %q", got)
+	}
+}
+
+func TestSyncGeneratedCreditsArtifactsWritesNewFiles(t *testing.T) {
+	root := t.TempDir()
+	desired := map[string][]byte{
+		filepath.Join(root, "test.md"): []byte("content"),
+	}
+	changed, err := SyncGeneratedCreditsArtifacts(root, desired)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if changed != 1 {
+		t.Fatalf("expected 1 changed file, got %d", changed)
+	}
+}
+
+func TestSyncGeneratedCreditsArtifactsNoChanges(t *testing.T) {
+	root := t.TempDir()
+	path := filepath.Join(root, "test.md")
+	if err := os.WriteFile(path, []byte("content"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+	desired := map[string][]byte{
+		path: []byte("content"),
+	}
+	changed, err := SyncGeneratedCreditsArtifacts(root, desired)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if changed != 0 {
+		t.Fatalf("expected 0 changed files, got %d", changed)
+	}
+}
+
+func TestSyncGeneratedCreditsArtifactsRemovesStale(t *testing.T) {
+	root := t.TempDir()
+	stalePath := filepath.Join(root, "stale.md")
+	if err := os.WriteFile(stalePath, []byte("stale"), 0o644); err != nil {
+		t.Fatalf("write stale file: %v", err)
+	}
+	desired := map[string][]byte{}
+	changed, err := SyncGeneratedCreditsArtifacts(root, desired)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if changed != 1 {
+		t.Fatalf("expected 1 removed file, got %d", changed)
+	}
+}
+
+func TestPrefixForDir(t *testing.T) {
+	prefixes := map[string]string{
+		"envi/music/westgate": "mus_wg_",
+	}
+	if got := PrefixForDir(prefixes, "envi/music/westgate"); got != "mus_wg_" {
+		t.Fatalf("expected 'mus_wg_', got %q", got)
+	}
+	if got := PrefixForDir(prefixes, "envi/music/other"); got != "" {
+		t.Fatalf("expected empty prefix, got %q", got)
+	}
+	if got := PrefixForDir(nil, "envi/music"); got != "" {
+		t.Fatalf("expected empty prefix for nil map, got %q", got)
+	}
+}
+
+func TestMaxMin(t *testing.T) {
+	if got := Min(3, 5); got != 3 {
+		t.Fatalf("Min(3,5) = %d, want 3", got)
+	}
+	if got := Max(3, 5); got != 5 {
+		t.Fatalf("Max(3,5) = %d, want 5", got)
+	}
+}
+
+func TestResolveFFmpegEnv(t *testing.T) {
+	t.Setenv("SOW_FFMPEG", "/custom/ffmpeg")
+	path, err := ResolveFFmpeg()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if path != "/custom/ffmpeg" {
+		t.Fatalf("expected '/custom/ffmpeg', got %q", path)
+	}
+}
+
+func TestResolveFFprobeEnv(t *testing.T) {
+	t.Setenv("SOW_FFPROBE", "/custom/ffprobe")
+	path, err := ResolveFFprobe()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if path != "/custom/ffprobe" {
+		t.Fatalf("expected '/custom/ffprobe', got %q", path)
+	}
+}

internal/music/naming.go

@@ -0,0 +1,197 @@
+package music
+
+import (
+	"crypto/sha1"
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+func GenerateStem(fileName, prefix string, used map[string]struct{}) (string, error) {
+	return GenerateStemWithMax(fileName, prefix, MaxStemLen, used)
+}
+
+func GenerateStemWithMax(fileName, prefix string, maxStemLen int, used map[string]struct{}) (string, error) {
+	if maxStemLen <= 0 {
+		maxStemLen = MaxStemLen
+	}
+	maxCore := maxStemLen - len(prefix)
+	if maxCore < 3 {
+		return "", fmt.Errorf("prefix too long: %q", prefix)
+	}
+	base := strings.TrimSuffix(fileName, filepath.Ext(fileName))
+	words := SlugWords(base)
+	core := MakeMusicCore(words, maxCore)
+	if core == "" {
+		sum := sha1.Sum([]byte(fileName))
+		core = fmt.Sprintf("%x", sum[:])[:maxCore]
+	}
+	stem := strings.TrimRight((prefix + core)[:Min(maxStemLen, len(prefix)+len(core))], "_")
+	if stem == "" {
+		return "", fmt.Errorf("could not derive music stem for %s", fileName)
+	}
+	return UniqueNameWithMax(stem, maxStemLen, used), nil
+}
+
+func SlugWords(value string) []string {
+	value = BracketRE.ReplaceAllString(value, " ")
+	value = strings.ReplaceAll(value, "&", " and ")
+	value = strings.ReplaceAll(value, "'", "")
+	value = strings.ReplaceAll(value, "\u2019", "")
+	value = strings.ToLower(value)
+	var ascii strings.Builder
+	for _, r := range value {
+		switch {
+		case r >= 'a' && r <= 'z':
+			ascii.WriteRune(r)
+		case r >= '0' && r <= '9':
+			ascii.WriteRune(r)
+		default:
+			ascii.WriteRune(' ')
+		}
+	}
+	rawWords := SplitRE.Split(ascii.String(), -1)
+	words := make([]string, 0, len(rawWords))
+	for _, word := range rawWords {
+		if word == "" {
+			continue
+		}
+		if _, drop := DropWords[word]; drop {
+			continue
+		}
+		if YearRE.MatchString(word) {
+			continue
+		}
+		words = append(words, word)
+	}
+	return words
+}
+
+func MakeMusicCore(words []string, maxCore int) string {
+	core := ""
+	for _, word := range words {
+		candidate := word
+		if core != "" {
+			candidate = core + "_" + word
+		}
+		if len(candidate) <= maxCore {
+			core = candidate
+			continue
+		}
+		break
+	}
+	if core != "" {
+		return core
+	}
+	abbrev := make([]string, 0, Min(4, len(words)))
+	for _, word := range words {
+		if len(abbrev) == 4 {
+			break
+		}
+		abbrev = append(abbrev, AbbreviateWord(word, 5))
+	}
+	for _, word := range abbrev {
+		candidate := word
+		if core != "" {
+			candidate = core + "_" + word
+		}
+		if len(candidate) <= maxCore {
+			core = candidate
+			continue
+		}
+		break
+	}
+	if core != "" {
+		return core
+	}
+	if len(words) > 0 {
+		return strings.Trim(words[0][:Min(maxCore, len(words[0]))], "_")
+	}
+	return ""
+}
+
+func AbbreviateWord(word string, maxLen int) string {
+	if len(word) <= maxLen {
+		return word
+	}
+	consonants := VowelRE.ReplaceAllString(word, "")
+	candidate := word[:1]
+	if len(consonants) > 1 {
+		candidate += consonants[1:]
+	}
+	if len(candidate) >= 3 {
+		return candidate[:Min(maxLen, len(candidate))]
+	}
+	return word[:Min(maxLen, len(word))]
+}
+
+func UniqueName(stem string, used map[string]struct{}) string {
+	return UniqueNameWithMax(stem, MaxStemLen, used)
+}
+
+func UniqueNameWithMax(stem string, maxStemLen int, used map[string]struct{}) string {
+	if maxStemLen <= 0 {
+		maxStemLen = MaxStemLen
+	}
+	if _, exists := used[stem]; !exists {
+		used[stem] = struct{}{}
+		return stem
+	}
+	for index := 1; ; index++ {
+		suffix := fmt.Sprintf("_%d", index)
+		prefixLen := Min(len(stem), Max(0, maxStemLen-len(suffix)))
+		candidate := strings.TrimRight(stem[:prefixLen], "_") + suffix
+		if _, exists := used[candidate]; exists {
+			continue
+		}
+		used[candidate] = struct{}{}
+		return candidate
+	}
+}
+
+func ReserveName(stem string, used map[string]struct{}) error {
+	stem = strings.ToLower(strings.TrimSpace(stem))
+	if stem == "" {
+		return fmt.Errorf("output filename is empty")
+	}
+	if _, exists := used[stem]; exists {
+		return fmt.Errorf("output filename %s collides with an existing asset", stem)
+	}
+	used[stem] = struct{}{}
+	return nil
+}
+
+func ValidateManualOutputFile(name string) error {
+	return ValidateManualOutputFileWithRules(name, ".bmu", MaxStemLen)
+}
+
+func ValidateManualOutputFileWithRules(name, extension string, maxStemLen int) error {
+	name = strings.ToLower(strings.TrimSpace(name))
+	extension = strings.ToLower(strings.TrimSpace(extension))
+	if extension == "" {
+		extension = ".bmu"
+	}
+	if maxStemLen <= 0 {
+		maxStemLen = MaxStemLen
+	}
+	if !strings.HasSuffix(name, extension) {
+		return fmt.Errorf("output file must end with %s", extension)
+	}
+	stem := strings.TrimSuffix(name, extension)
+	if stem == "" {
+		return fmt.Errorf("output file stem is empty")
+	}
+	if len(stem) > maxStemLen {
+		return fmt.Errorf("output file stem %q exceeds %d characters", stem, maxStemLen)
+	}
+	for _, r := range stem {
+		switch {
+		case r >= 'a' && r <= 'z':
+		case r >= '0' && r <= '9':
+		case r == '_':
+		default:
+			return fmt.Errorf("output file stem %q contains unsupported character %q", stem, string(r))
+		}
+	}
+	return nil
+}