mpckit/internal/project/project.go

// Package project is the MPCkit domain model: one MPC Sample project and
// every edit 0.5.0 makes to it. Edits follow the verified recipes in
// docs/xpj-format-and-scope.md section 3 and change only the fields those
// recipes name; everything else is written back as read.
package project

import (
	"bytes"
	_ "embed"
	"errors"
	"fmt"
	"path/filepath"
	"strings"

	"git.monoexp.com/bajdev/mpckit/internal/xpj"
)

//go:embed template/DemoBlank.xpj
var templateXPJ []byte

// Device and format limits.
const (
	Pads          = 128 // 8 banks x 16
	MaxSamples    = 128
	MaxSequences  = 128
	PulsesPerBar  = 3840 // 4/4 at 960 pulses per beat
	FirstNote     = 36   // a note event for pad slot n stores note 36 + n
	TestedVersion = 28   // data.version of firmware 1.3.0.12
	DataSuffix    = "_[ProjectData]"
)

// Tuning ranges for 0.5.0 (format doc, open question 1a).
const (
	MinCoarse, MaxCoarse = -24, 24
	MinFine, MaxFine     = -90, 90
)

// MaxMuteGroup is the highest mute group the device offers; 0 is off.
// Device checkpoint A3, 2026-11-10.
const MaxMuteGroup = 16

// BPM range of the device's tempo control (device checkpoint A5, 2026-11-10).
const (
	MinBPM = 20.0
	MaxBPM = 999.0
)

// DefaultBPM is used for a new sequence when no sequence has been edited.
const DefaultBPM = 120.0

// Project is one project: the parsed file plus what the file does not hold.
type Project struct {
	// Name is the project name: the .xpj file name and data folder prefix.
	Name string
	// SourceDir is the data folder of a loaded project; empty for a new one.
	SourceDir string
	// Sources maps each pool file name to the absolute path it is copied
	// from at export.
	Sources map[string]string
	// Dirty is set by every edit.
	Dirty bool

	file *xpj.File
	data *xpj.Node

	lastBPM float64 // BPM of the most recently edited sequence; 0 if none
}

var template = mustTemplate()

type tmpl struct {
	pad      *xpj.Node // one blank pad (all 128 are identical)
	sequence *xpj.Node // the blank project's single sequence entry {key, value}
}

func mustTemplate() tmpl {
	f, err := xpj.Read(bytes.NewReader(templateXPJ))
	if err != nil {
		panic("project: embedded template: " + err.Error())
	}
	d, _ := f.Data()
	pad, err := d.Get("tracks[0].program.drum.instruments[0]")
	if err != nil {
		panic("project: embedded template: " + err.Error())
	}
	seq, err := d.Get("sequences[0]")
	if err != nil {
		panic("project: embedded template: " + err.Error())
	}
	return tmpl{pad: pad, sequence: seq}
}

// New returns a new project built from the blank template.
func New(name string) (*Project, error) {
	if err := ValidName(name); err != nil {
		return nil, err
	}
	f, err := xpj.Read(bytes.NewReader(templateXPJ))
	if err != nil {
		return nil, err
	}
	return wrap(f, name, "")
}

// Load reads the .xpj at path. The project name is taken from the file name
// and samples are expected in the sibling "<name>_[ProjectData]" folder.
// The returned warnings describe differences from the tested firmware;
// the project is still usable.
func Load(path string) (*Project, []string, error) {
	abs, err := filepath.Abs(path)
	if err != nil {
		return nil, nil, err
	}
	f, err := xpj.ReadFile(abs)
	if err != nil {
		return nil, nil, err
	}
	name := strings.TrimSuffix(filepath.Base(abs), filepath.Ext(abs))
	dataDir := filepath.Join(filepath.Dir(abs), name+DataSuffix)
	p, err := wrap(f, name, dataDir)
	if err != nil {
		return nil, nil, err
	}

	var warnings []string
	if f.Header[1] != xpj.TestedHeader[1] {
		warnings = append(warnings, fmt.Sprintf("saved by firmware %s; MPCkit is tested with %s", f.Header[1], xpj.TestedHeader[1]))
	}
	if v, err := p.data.Lookup("version").Int(); err != nil || v != TestedVersion {
		warnings = append(warnings, fmt.Sprintf("project data version %d; MPCkit is tested with %d", v, TestedVersion))
	}
	for _, e := range p.pool().Items {
		file := e.Lookup("path").Text
		p.Sources[file] = filepath.Join(dataDir, file)
	}
	return p, warnings, nil
}

func wrap(f *xpj.File, name, sourceDir string) (*Project, error) {
	d, err := f.Data()
	if err != nil {
		return nil, err
	}
	p := &Project{Name: name, SourceDir: sourceDir, Sources: map[string]string{}, file: f, data: d}
	for _, path := range []string{"samples", "tracks[0].samples", "tracks[0].program.drum.instruments", "sequences"} {
		n, err := d.Get(path)
		if err != nil {
			return nil, fmt.Errorf("project: %w", err)
		}
		if n.Kind != xpj.Array {
			return nil, fmt.Errorf("project: %s is not a list", path)
		}
	}
	if n := len(p.pads().Items); n != Pads {
		return nil, fmt.Errorf("project: %d pads, want %d", n, Pads)
	}
	return p, nil
}

// File returns the project file for writing. Callers must not edit it.
func (p *Project) File() *xpj.File { return p.file }

// SetName renames the project. Nothing inside the file changes.
func (p *Project) SetName(name string) error {
	if err := ValidName(name); err != nil {
		return err
	}
	if name != p.Name {
		p.Name = name
		p.Dirty = true
	}
	return nil
}

// ValidName checks a project or sequence name: not empty, and free of
// characters that are illegal in file names on Windows or FAT.
func ValidName(name string) error {
	if strings.TrimSpace(name) == "" {
		return errors.New("name is empty")
	}
	for _, r := range name {
		if r < 0x20 || strings.ContainsRune(`<>:"/\|?*`, r) {
			if r < 0x20 {
				return errors.New("name contains a control character")
			}
			return fmt.Errorf("name contains %q, which is not allowed in file names", r)
		}
	}
	if strings.HasSuffix(name, ".") || strings.HasSuffix(name, " ") {
		return errors.New("name cannot end with a dot or a space")
	}
	base := strings.ToUpper(name)
	if i := strings.IndexByte(base, '.'); i >= 0 {
		base = base[:i]
	}
	switch base {
	case "CON", "PRN", "AUX", "NUL",
		"COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
		"LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9":
		return fmt.Errorf("%q is a reserved name on Windows", name)
	}
	return nil
}

// Slot helpers. A slot is 0-127: bank x 16 + pad - 1.

// SlotName returns the pad label for a slot, e.g. 0 -> "A1", 17 -> "B2".
func SlotName(slot int) string {
	return fmt.Sprintf("%c%d", 'A'+slot/16, slot%16+1)
}

func checkSlot(slot int) error {
	if slot < 0 || slot >= Pads {
		return fmt.Errorf("pad slot %d out of range 0-%d", slot, Pads-1)
	}
	return nil
}

func (p *Project) pads() *xpj.Node {
	n, _ := p.data.Get("tracks[0].program.drum.instruments")
	return n
}

func (p *Project) pad(slot int) *xpj.Node { return p.pads().Items[slot] }

func layer(pad *xpj.Node) (*xpj.Node, error) {
	return pad.Get("layersv[0]")
}

// pool is samples[]; trackPool is tracks[0].samples[]. The device keeps
// the same entries in both, appending to the first and prepending to the
// second.
func (p *Project) pool() *xpj.Node {
	n, _ := p.data.Get("samples")
	return n
}

func (p *Project) trackPool() *xpj.Node {
	n, _ := p.data.Get("tracks[0].samples")
	return n
}

func (p *Project) sequences() *xpj.Node {
	n, _ := p.data.Get("sequences")
	return n
}

// edit applies several Sets and keeps the first error, so an operation can
// list its writes plainly. Paths come from the template; a failure means the
// loaded file has a different shape.
type edit struct{ err error }

func (e *edit) set(n *xpj.Node, path string, v *xpj.Node) {
	if e.err == nil {
		if err := n.Set(path, v); err != nil {
			e.err = fmt.Errorf("project: %w", err)
		}
	}
}