From ef6d27e80fb71ee3957db6fa706f1811dc6a0eb2 Mon Sep 17 00:00:00 2001
From: Baron Luca <baron_luca@hotmail.it>
Date: Wed, 19 Aug 2026 13:49:13 +0200
Subject: [PATCH 1/5] feat(charts): add chart creator foundation

---
 docs/README.md                                |   1 +
 docs/development/chart-creator.md             |  49 +++
 .../Runtime/Gameplay/ChartCreator.cs          | 363 ++++++++++++++++++
 .../Runtime/Gameplay/ChartCreator.cs.meta     |  11 +
 .../Gameplay/GameplayHighwayController.cs     | 137 ++++++-
 .../Gameplay/GameplaySessionDefinition.cs     |  48 ++-
 .../Runtime/MainMenu/MainMenuController.cs    |  24 ++
 .../Tests/EditMode/ChartCreatorTests.cs       | 174 +++++++++
 .../Tests/EditMode/ChartCreatorTests.cs.meta  |  11 +
 .../Tests/PlayMode/MainMenuPlayModeTests.cs   |  24 ++
 .../HitTheKit/UI/Gameplay/GameplayHighway.uss |   7 +
 .../UI/Gameplay/GameplayHighway.uxml          |  11 +
 .../Assets/HitTheKit/UI/MainMenu/MainMenu.uss |  22 +-
 .../HitTheKit/UI/MainMenu/MainMenu.uxml       |   5 +-
 14 files changed, 874 insertions(+), 13 deletions(-)
 create mode 100644 docs/development/chart-creator.md
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs.meta
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs.meta

diff --git a/docs/README.md b/docs/README.md
index 5fc5e9d..850419a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -43,6 +43,7 @@ without creating an unreviewed second source of truth.
 
 - [DSP song clock](development/dsp-song-clock.md)
 - [Chart timeline](development/chart-timeline.md)
+- [Chart Creator foundation](development/chart-creator.md)
 - [Demo-song vertical slice](development/demo-song-vertical-slice.md)
 - [Keyboard hit matching](development/keyboard-hit-matching.md)
 - [Pad visuals](development/pad-visuals.md)
diff --git a/docs/development/chart-creator.md b/docs/development/chart-creator.md
new file mode 100644
index 0000000..e6dccec
--- /dev/null
+++ b/docs/development/chart-creator.md
@@ -0,0 +1,49 @@
+# Chart Creator foundation
+
+Chart Creator turns a performance from the existing keyboard/CoreMIDI gameplay
+input into a reviewable schema-v1 chart draft. It deliberately reuses the real
+gameplay scene rather than maintaining a second audio clock, input mapper, or
+timeline.
+
+## Workflow
+
+1. Add or select a playable song in the Song Library.
+2. Choose its difficulty and practice speed.
+3. Select **Record chart**.
+4. Play during the normal count-in and backing track. Hits before song time zero
+   or beyond the declared song duration are ignored.
+5. At the result screen, review the captured-hit count and save the raw timing,
+   or quantize non-destructively to an eighth- or sixteenth-note grid.
+
+Keyboard and MIDI events reach the recorder through `HitMatchingPrototype`'s
+`InputProcessed` boundary. Consequently, the existing per-source timing offset
+is applied before recording. A take made at a reduced practice speed is scaled
+back to the source song's original timeline before it is serialized.
+
+## Output and rights boundary
+
+The exporter creates a new, never-overwritten folder under
+`~/Documents/HTKSongs` containing only:
+
+- `song.json`;
+- `notes.json`.
+
+The publish is atomic and both documents are parsed by the production loaders
+before the folder becomes visible. The manifest declares chart availability but
+keeps audio as `missing`. Chart Creator never copies, embeds, downloads, or
+redistributes the source audio. To play or share the take, the user must add an
+audio file they are entitled to use and update the local binding explicitly.
+
+The exported title is marked `Recorded Take` and the difficulty hint says that
+the performance must be reviewed before sharing. This is a captured performance,
+not a claim of authoritative transcription.
+
+## Current foundation limits
+
+- A playable Song Library entry is required; audio import/file-picker UI is not
+  part of this first foundation.
+- Editing individual notes is not yet available. Raw/1/8/1/16 save choices are
+  the initial review tools.
+- The schema currently stores pad and time. Velocity and articulation remain in
+  the in-memory take but schema v1 does not serialize them.
+- Exported takes are intentionally non-playable until authorized audio is bound.
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
new file mode 100644
index 0000000..d6d2883
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
@@ -0,0 +1,363 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Globalization;
+using System.IO;
+using System.Text;
+using HitTheKit.Core;
+using HitTheKit.Unity.Charts;
+using HitTheKit.Unity.Input;
+
+namespace HitTheKit.Unity.Gameplay
+{
+    public enum ChartQuantization
+    {
+        None,
+        EighthNote,
+        SixteenthNote
+    }
+
+    public sealed class RecordedChartHit
+    {
+        internal RecordedChartHit(DrumInputEvent input, int recordingIndex)
+        {
+            Pad = input.Pad;
+            Velocity = input.Velocity;
+            TimeSeconds = input.SongTimeSeconds;
+            Source = input.Source;
+            RecordingIndex = recordingIndex;
+        }
+
+        public DrumPad Pad { get; }
+        public int Velocity { get; }
+        public double TimeSeconds { get; }
+        public DrumInputSource Source { get; }
+        internal int RecordingIndex { get; }
+    }
+
+    public sealed class ChartRecordingDraft
+    {
+        internal ChartRecordingDraft(double durationSeconds, IReadOnlyList<RecordedChartHit> hits)
+        {
+            DurationSeconds = durationSeconds;
+            var copy = new RecordedChartHit[hits.Count];
+            for (int index = 0; index < hits.Count; index++) copy[index] = hits[index];
+            Hits = Array.AsReadOnly(copy);
+        }
+
+        public double DurationSeconds { get; }
+        public IReadOnlyList<RecordedChartHit> Hits { get; }
+    }
+
+    public sealed class ChartRecordingSession
+    {
+        public const int MaximumHits = 100000;
+        private readonly double durationSeconds;
+        private readonly double outputTimeScale;
+        private readonly List<RecordedChartHit> hits = new List<RecordedChartHit>();
+
+        public ChartRecordingSession(double durationSeconds, double outputTimeScale = 1.0)
+        {
+            if (!IsFinite(durationSeconds) || durationSeconds <= 0)
+                throw new ArgumentOutOfRangeException(nameof(durationSeconds));
+            if (!IsFinite(outputTimeScale) || outputTimeScale <= 0)
+                throw new ArgumentOutOfRangeException(nameof(outputTimeScale));
+            this.durationSeconds = durationSeconds;
+            this.outputTimeScale = outputTimeScale;
+        }
+
+        public bool IsRecording { get; private set; } = true;
+        public int HitCount => hits.Count;
+        public int IgnoredCount { get; private set; }
+
+        public bool Record(DrumInputEvent input)
+        {
+            if (!IsRecording) return false;
+            if (input.SongTimeSeconds < 0 || input.SongTimeSeconds > durationSeconds)
+            {
+                IgnoredCount++;
+                return false;
+            }
+            if (hits.Count >= MaximumHits)
+                throw new InvalidOperationException($"A chart recording cannot exceed {MaximumHits} hits.");
+
+            hits.Add(new RecordedChartHit(input.WithSongTime(input.SongTimeSeconds * outputTimeScale), hits.Count));
+            return true;
+        }
+
+        public ChartRecordingDraft Finish()
+        {
+            IsRecording = false;
+            return new ChartRecordingDraft(durationSeconds * outputTimeScale, hits);
+        }
+
+        public void Restart()
+        {
+            hits.Clear();
+            IgnoredCount = 0;
+            IsRecording = true;
+        }
+
+        private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+    }
+
+    public sealed class ChartCreatorMetadata
+    {
+        public ChartCreatorMetadata(
+            string sourceSongId,
+            string title,
+            string artist,
+            string difficulty,
+            double bpm,
+            int bars,
+            int beatsPerBar)
+        {
+            ValidateIdentifier(sourceSongId, nameof(sourceSongId));
+            if (string.IsNullOrWhiteSpace(title)) throw new ArgumentException("Title is required.", nameof(title));
+            if (string.IsNullOrWhiteSpace(artist)) throw new ArgumentException("Artist is required.", nameof(artist));
+            if (!Contains(ChartLoader.SupportedDifficulties, difficulty))
+                throw new ArgumentOutOfRangeException(nameof(difficulty));
+            if (!IsFinite(bpm) || bpm <= 0) throw new ArgumentOutOfRangeException(nameof(bpm));
+            if (bars <= 0) throw new ArgumentOutOfRangeException(nameof(bars));
+            if (beatsPerBar <= 0) throw new ArgumentOutOfRangeException(nameof(beatsPerBar));
+
+            SourceSongId = sourceSongId;
+            Title = title.Trim();
+            Artist = artist.Trim();
+            Difficulty = difficulty;
+            Bpm = bpm;
+            Bars = bars;
+            BeatsPerBar = beatsPerBar;
+        }
+
+        public string SourceSongId { get; }
+        public string Title { get; }
+        public string Artist { get; }
+        public string Difficulty { get; }
+        public double Bpm { get; }
+        public int Bars { get; }
+        public int BeatsPerBar { get; }
+
+        internal static void ValidateIdentifier(string value, string parameter)
+        {
+            if (string.IsNullOrWhiteSpace(value) || value.Length > 80)
+                throw new ArgumentException("Song ID is required and must not exceed 80 characters.", parameter);
+            for (int index = 0; index < value.Length; index++)
+            {
+                char character = value[index];
+                if (!(character >= 'a' && character <= 'z') &&
+                    !(character >= '0' && character <= '9') && character != '-')
+                    throw new ArgumentException("Song ID must use lowercase letters, numbers, and hyphens.", parameter);
+            }
+        }
+
+        private static bool Contains(IReadOnlyList<string> values, string value)
+        {
+            for (int index = 0; index < values.Count; index++)
+                if (string.Equals(values[index], value, StringComparison.Ordinal)) return true;
+            return false;
+        }
+
+        private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+    }
+
+    public static class ChartCreatorJson
+    {
+        public static string Serialize(
+            ChartRecordingDraft draft,
+            string difficulty,
+            double bpm,
+            ChartQuantization quantization)
+        {
+            if (draft == null) throw new ArgumentNullException(nameof(draft));
+            if (!Enum.IsDefined(typeof(ChartQuantization), quantization))
+                throw new ArgumentOutOfRangeException(nameof(quantization));
+            if (!IsFinite(bpm) || bpm <= 0) throw new ArgumentOutOfRangeException(nameof(bpm));
+            bool supported = false;
+            for (int index = 0; index < ChartLoader.SupportedDifficulties.Count; index++)
+                if (string.Equals(ChartLoader.SupportedDifficulties[index], difficulty, StringComparison.Ordinal))
+                    supported = true;
+            if (!supported) throw new ArgumentOutOfRangeException(nameof(difficulty));
+
+            var projected = new List<ProjectedHit>(draft.Hits.Count);
+            for (int index = 0; index < draft.Hits.Count; index++)
+            {
+                RecordedChartHit hit = draft.Hits[index];
+                double time = Quantize(hit.TimeSeconds, bpm, quantization);
+                time = Math.Max(0, Math.Min(draft.DurationSeconds, time));
+                projected.Add(new ProjectedHit(time, hit.Pad, hit.RecordingIndex));
+            }
+            projected.Sort((left, right) =>
+            {
+                int byTime = left.TimeSeconds.CompareTo(right.TimeSeconds);
+                return byTime != 0 ? byTime : left.RecordingIndex.CompareTo(right.RecordingIndex);
+            });
+
+            var json = new StringBuilder(128 + projected.Count * 48);
+            json.Append("{\n  \"version\": 1,\n  \"offsetSeconds\": 0,\n  \"difficulties\": {\n    \"")
+                .Append(difficulty)
+                .Append("\": [");
+            for (int index = 0; index < projected.Count; index++)
+            {
+                ProjectedHit hit = projected[index];
+                json.Append(index == 0 ? "\n      " : ",\n      ")
+                    .Append("{ \"time\": ")
+                    .Append(hit.TimeSeconds.ToString("0.#########", CultureInfo.InvariantCulture))
+                    .Append(", \"pad\": \"")
+                    .Append(PadId(hit.Pad))
+                    .Append("\" }");
+            }
+            if (projected.Count > 0) json.Append('\n').Append("    ");
+            json.Append("]\n  }\n}\n");
+
+            string result = json.ToString();
+            new ChartLoader().Load(result, difficulty);
+            return result;
+        }
+
+        private static double Quantize(double value, double bpm, ChartQuantization quantization)
+        {
+            int subdivisions;
+            switch (quantization)
+            {
+                case ChartQuantization.None: return value;
+                case ChartQuantization.EighthNote: subdivisions = 2; break;
+                case ChartQuantization.SixteenthNote: subdivisions = 4; break;
+                default: throw new ArgumentOutOfRangeException(nameof(quantization));
+            }
+            double step = 60.0 / bpm / subdivisions;
+            return Math.Round(value / step, MidpointRounding.AwayFromZero) * step;
+        }
+
+        private static string PadId(DrumPad pad)
+        {
+            switch (pad)
+            {
+                case DrumPad.Kick: return "kick";
+                case DrumPad.Snare: return "snare";
+                case DrumPad.HiHat: return "hiHat";
+                case DrumPad.Tom1: return "tom1";
+                case DrumPad.Tom2: return "tom2";
+                case DrumPad.FloorTom: return "floorTom";
+                case DrumPad.Crash: return "crash";
+                case DrumPad.Ride: return "ride";
+                default: throw new ArgumentOutOfRangeException(nameof(pad));
+            }
+        }
+
+        private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+
+        private sealed class ProjectedHit
+        {
+            public ProjectedHit(double timeSeconds, DrumPad pad, int recordingIndex)
+            {
+                TimeSeconds = timeSeconds;
+                Pad = pad;
+                RecordingIndex = recordingIndex;
+            }
+            public double TimeSeconds { get; }
+            public DrumPad Pad { get; }
+            public int RecordingIndex { get; }
+        }
+    }
+
+    public sealed class ChartCreatorExportResult
+    {
+        internal ChartCreatorExportResult(string songId, string folderPath, string chartPath, string manifestPath)
+        {
+            SongId = songId;
+            FolderPath = folderPath;
+            ChartPath = chartPath;
+            ManifestPath = manifestPath;
+        }
+        public string SongId { get; }
+        public string FolderPath { get; }
+        public string ChartPath { get; }
+        public string ManifestPath { get; }
+    }
+
+    public sealed class ChartCreatorExporter
+    {
+        private static readonly UTF8Encoding Utf8WithoutBom = new UTF8Encoding(false);
+
+        public ChartCreatorExportResult ExportChartOnly(
+            ChartRecordingDraft draft,
+            ChartCreatorMetadata metadata,
+            ChartQuantization quantization,
+            string libraryRoot,
+            DateTimeOffset createdAtUtc)
+        {
+            if (draft == null) throw new ArgumentNullException(nameof(draft));
+            if (draft.Hits.Count == 0)
+                throw new InvalidOperationException("A recorded chart must contain at least one hit.");
+            if (metadata == null) throw new ArgumentNullException(nameof(metadata));
+            if (string.IsNullOrWhiteSpace(libraryRoot)) throw new ArgumentException("Library root is required.", nameof(libraryRoot));
+            if (createdAtUtc.Offset != TimeSpan.Zero) throw new ArgumentException("Creation time must be UTC.", nameof(createdAtUtc));
+
+            string root = Path.GetFullPath(libraryRoot);
+            Directory.CreateDirectory(root);
+            string prefix = metadata.SourceSongId.Length <= 48 ? metadata.SourceSongId : metadata.SourceSongId.Substring(0, 48).TrimEnd('-');
+            string baseId = $"{prefix}-take-{createdAtUtc:yyyyMMdd-HHmmss}";
+            string songId = UniqueSongId(root, baseId);
+            string destination = Path.Combine(root, songId);
+            string temporary = Path.Combine(root, $".hitthekit-chart-{Guid.NewGuid():N}");
+            Directory.CreateDirectory(temporary);
+            try
+            {
+                string chartJson = ChartCreatorJson.Serialize(draft, metadata.Difficulty, metadata.Bpm, quantization);
+                string chartPath = Path.Combine(temporary, "notes.json");
+                string manifestPath = Path.Combine(temporary, "song.json");
+                File.WriteAllText(chartPath, chartJson, Utf8WithoutBom);
+                File.WriteAllText(manifestPath, Manifest(songId, metadata), Utf8WithoutBom);
+
+                // Validate both public formats before the atomic publish into HTKSongs.
+                new ChartLoader().Load(chartJson, metadata.Difficulty);
+                new SongLibraryDiscovery().Parse(File.ReadAllText(manifestPath), temporary, SongLibraryOrigin.UserFolder);
+                Directory.Move(temporary, destination);
+                return new ChartCreatorExportResult(
+                    songId,
+                    destination,
+                    Path.Combine(destination, "notes.json"),
+                    Path.Combine(destination, "song.json"));
+            }
+            catch
+            {
+                if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                throw;
+            }
+        }
+
+        private static string UniqueSongId(string root, string baseId)
+        {
+            string value = baseId;
+            int suffix = 2;
+            while (Directory.Exists(Path.Combine(root, value))) value = $"{baseId}-{suffix++}";
+            ChartCreatorMetadata.ValidateIdentifier(value, nameof(baseId));
+            return value;
+        }
+
+        private static string Manifest(string songId, ChartCreatorMetadata metadata)
+        {
+            return "{\n" +
+                   "  \"schemaVersion\": 1,\n" +
+                   $"  \"id\": \"{Escape(songId)}\",\n" +
+                   $"  \"title\": \"{Escape(metadata.Title + " · Recorded Take")}\",\n" +
+                   $"  \"artist\": \"{Escape(metadata.Artist)}\",\n" +
+                   $"  \"bpm\": {metadata.Bpm.ToString("0.#########", CultureInfo.InvariantCulture)},\n" +
+                   $"  \"bars\": {metadata.Bars},\n" +
+                   $"  \"beatsPerBar\": {metadata.BeatsPerBar},\n" +
+                   "  \"difficultyHint\": \"Recorded performance · review before sharing\",\n" +
+                   "  \"sortOrder\": 0,\n" +
+                   "  \"audioAvailability\": \"missing\",\n" +
+                   "  \"chartAvailability\": \"available\",\n" +
+                   "  \"chartFile\": \"notes.json\"\n" +
+                   "}\n";
+        }
+
+        private static string Escape(string value) => value
+            .Replace("\\", "\\\\")
+            .Replace("\"", "\\\"")
+            .Replace("\r", "\\r")
+            .Replace("\n", "\\n");
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs.meta
new file mode 100644
index 0000000..ea60eb3
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: f78758e52aef4c5b8c593dc737ae4a4d
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
index 4f14249..eb4ed72 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
@@ -75,6 +75,12 @@ public sealed class GameplayHighwayController : MonoBehaviour
         private Label resultBreakdownLabel;
         private Label resultPracticeLabel;
         private Label resultCalibrationLabel;
+        private VisualElement chartCreatorResults;
+        private Label chartCreatorSummaryLabel;
+        private Label chartCreatorStatusLabel;
+        private Button chartSaveRawButton;
+        private Button chartSaveEighthButton;
+        private Button chartSaveSixteenthButton;
         private GameplayHighwaySurface surface;
         private GameplayKitSurface kitSurface;
         private bool showInstructionalKit;
@@ -93,6 +99,8 @@ public sealed class GameplayHighwayController : MonoBehaviour
         private AudioClip metronomeClip;
         private bool metronomeScheduled;
         private bool resultRecorded;
+        private ChartRecordingSession chartRecording;
+        private ChartRecordingDraft chartDraft;
 
         public event Action<GameplayPresentationTheme> ThemeChanged;
 
@@ -114,6 +122,8 @@ public sealed class GameplayHighwayController : MonoBehaviour
         public GameplaySessionDefinition CurrentSession =>
             sessionCoordinator?.Session ?? GameplaySessionContext.Current;
         public double CurrentAttemptPracticeSeconds => practiceTimer.CurrentAttemptSeconds;
+        public int RecordedChartHitCount => chartRecording?.HitCount ?? chartDraft?.Hits.Count ?? 0;
+        public string LastChartExportPath { get; private set; }
 
         private void Awake()
         {
@@ -141,6 +151,7 @@ private void Start()
             BindNavigation();
             Subscribe();
             InitializeAudioFeedback();
+            InitializeChartCreator();
             SetTheme(CurrentSession.Theme);
             RefreshSessionCopy();
         }
@@ -264,6 +275,12 @@ private void BindView()
             resultBreakdownLabel = root.Q<Label>("result-breakdown");
             resultPracticeLabel = root.Q<Label>("result-practice");
             resultCalibrationLabel = root.Q<Label>("result-calibration");
+            chartCreatorResults = root.Q<VisualElement>("chart-creator-results");
+            chartCreatorSummaryLabel = root.Q<Label>("chart-creator-summary");
+            chartCreatorStatusLabel = root.Q<Label>("chart-creator-status");
+            chartSaveRawButton = root.Q<Button>("chart-save-raw");
+            chartSaveEighthButton = root.Q<Button>("chart-save-eighth");
+            chartSaveSixteenthButton = root.Q<Button>("chart-save-sixteenth");
             PlayerPreferencesSnapshot preferences = PlayerPreferencesRuntime.Current.Snapshot;
             root.EnableInClassList("gameplay--high-contrast", preferences.HighContrast);
             root.EnableInClassList("gameplay--reduced-motion", preferences.ReducedMotion);
@@ -392,6 +409,7 @@ private void RefreshPresentation()
 
         private void HandleInputProcessed(DrumInputEvent input, HitResult result)
         {
+            if (CurrentSession.IsChartCreator) chartRecording?.Record(input);
             latestPulsePad = input.Pad;
             pulseDeadlines[input.Pad] = Time.unscaledTime + PulseDurationSeconds;
             lastCalibrationSource = input.Source == DrumInputSource.Midi
@@ -488,6 +506,9 @@ public void RestartRun()
             FlushPracticeTime();
             practiceTimer.ResetAttempt();
             resultRecorded = false;
+            chartDraft = null;
+            LastChartExportPath = null;
+            chartRecording?.Restart();
             scoreTracker.Reset();
             keyboardCalibration.Reset();
             midiCalibration.Reset();
@@ -531,17 +552,47 @@ private void ShowResults(HitMatchingSnapshot matchingSnapshot)
             RunState = GameplayRunState.Results;
             FlushPracticeTime();
             GameplayScoreSnapshot score = scoreTracker.Snapshot;
-            RecordCompletedSession(matchingSnapshot, score);
+            if (CurrentSession.IsChartCreator)
+            {
+                chartDraft = chartRecording?.Finish();
+            }
+            else
+            {
+                RecordCompletedSession(matchingSnapshot, score);
+            }
             resultRecorded = true;
-            resultRankLabel.text = score.Rank;
-            resultScoreLabel.text = score.Score.ToString("N0", CultureInfo.InvariantCulture);
-            resultAccuracyLabel.text = $"{score.Accuracy:0.0}%";
-            resultComboLabel.text = score.MaxCombo.ToString(CultureInfo.InvariantCulture);
-            resultBreakdownLabel.text =
-                $"PERFECT {matchingSnapshot.PerfectCount}   GOOD {matchingSnapshot.GoodCount}   " +
-                $"EARLY/LATE {matchingSnapshot.EarlyCount + matchingSnapshot.LateCount}   MISS {matchingSnapshot.MissCount}";
-            RenderPracticeRecommendation();
-            RenderCalibrationRecommendation();
+            if (CurrentSession.IsChartCreator)
+            {
+                int hitCount = chartDraft?.Hits.Count ?? 0;
+                resultRankLabel.text = "REC";
+                resultScoreLabel.text = hitCount.ToString("N0", CultureInfo.InvariantCulture);
+                resultAccuracyLabel.text = "TAKE";
+                resultComboLabel.text = "—";
+                resultBreakdownLabel.text = $"{hitCount} COLPI CATTURATI · TIMELINE DSP · AUDIO ESCLUSO";
+                resultPracticeLabel.text = "RIVEDI LA TAKE E SCEGLI LA QUANTIZZAZIONE";
+                resultCalibrationLabel.text = "RAW conserva il timing; 1/8 e 1/16 allineano alla griglia.";
+                resultApplyCalibrationButton.SetEnabled(false);
+                if (chartCreatorSummaryLabel != null)
+                    chartCreatorSummaryLabel.text = $"{hitCount} COLPI REGISTRATI · {CurrentSession.Difficulty.ToUpperInvariant()}";
+                if (chartCreatorStatusLabel != null) chartCreatorStatusLabel.text = string.Empty;
+                chartSaveRawButton?.SetEnabled(hitCount > 0);
+                chartSaveEighthButton?.SetEnabled(hitCount > 0);
+                chartSaveSixteenthButton?.SetEnabled(hitCount > 0);
+                SetDisplayed(chartCreatorResults, true);
+            }
+            else
+            {
+                resultRankLabel.text = score.Rank;
+                resultScoreLabel.text = score.Score.ToString("N0", CultureInfo.InvariantCulture);
+                resultAccuracyLabel.text = $"{score.Accuracy:0.0}%";
+                resultComboLabel.text = score.MaxCombo.ToString(CultureInfo.InvariantCulture);
+                resultBreakdownLabel.text =
+                    $"PERFECT {matchingSnapshot.PerfectCount}   GOOD {matchingSnapshot.GoodCount}   " +
+                    $"EARLY/LATE {matchingSnapshot.EarlyCount + matchingSnapshot.LateCount}   MISS {matchingSnapshot.MissCount}";
+                RenderPracticeRecommendation();
+                RenderCalibrationRecommendation();
+                SetDisplayed(chartCreatorResults, false);
+            }
             SetDisplayed(resultsOverlay, true);
         }
 
@@ -552,6 +603,66 @@ private void RefreshSessionCopy()
             if (trackMetaLabel != null) trackMetaLabel.text = sessionCoordinator.Metadata;
             if (resultMenuButton != null) resultMenuButton.text = sessionCoordinator.Session.ReturnButtonLabel;
             if (sessionKickerLabel != null) sessionKickerLabel.text = sessionCoordinator.Session.Kicker;
+            SetDisplayed(chartCreatorResults, sessionCoordinator.Session.IsChartCreator && RunState == GameplayRunState.Results);
+        }
+
+        private void InitializeChartCreator()
+        {
+            if (!CurrentSession.IsChartCreator)
+            {
+                chartRecording = null;
+                chartDraft = null;
+                return;
+            }
+
+            double playbackDuration = CurrentSession.Bars * CurrentSession.BeatsPerBar * 60.0 / CurrentSession.Bpm;
+            chartRecording = new ChartRecordingSession(playbackDuration, CurrentSession.SpeedMultiplier);
+            chartDraft = null;
+        }
+
+        public ChartCreatorExportResult SaveChartRecording(ChartQuantization quantization)
+        {
+            if (!CurrentSession.IsChartCreator)
+                throw new InvalidOperationException("The current session is not recording a chart.");
+            if (chartDraft == null)
+                throw new InvalidOperationException("Finish the take before saving its chart.");
+
+            double originalBpm = CurrentSession.Bpm / CurrentSession.SpeedMultiplier;
+            var metadata = new ChartCreatorMetadata(
+                CurrentSession.SongId,
+                CurrentSession.Title,
+                CurrentSession.Subtitle,
+                CurrentSession.Difficulty,
+                originalBpm,
+                CurrentSession.Bars,
+                CurrentSession.BeatsPerBar);
+            ChartCreatorExportResult result = new ChartCreatorExporter().ExportChartOnly(
+                chartDraft,
+                metadata,
+                quantization,
+                SongLibraryRuntime.UserRoot,
+                DateTimeOffset.UtcNow);
+            LastChartExportPath = result.FolderPath;
+            if (chartCreatorStatusLabel != null)
+                chartCreatorStatusLabel.text = $"SALVATO · {result.SongId} · AGGIUNGI SOLO AUDIO AUTORIZZATO";
+            return result;
+        }
+
+        private void SaveRawChart() => TrySaveChart(ChartQuantization.None);
+        private void SaveEighthChart() => TrySaveChart(ChartQuantization.EighthNote);
+        private void SaveSixteenthChart() => TrySaveChart(ChartQuantization.SixteenthNote);
+
+        private void TrySaveChart(ChartQuantization quantization)
+        {
+            try
+            {
+                SaveChartRecording(quantization);
+            }
+            catch (Exception exception)
+            {
+                if (chartCreatorStatusLabel != null)
+                    chartCreatorStatusLabel.text = $"SALVATAGGIO NON RIUSCITO · {exception.Message}";
+            }
         }
 
         private void InitializeAudioFeedback()
@@ -646,6 +757,9 @@ private void BindRunControls()
             if (resultRestartButton != null) resultRestartButton.clicked += RestartRun;
             if (resultMenuButton != null) resultMenuButton.clicked += ReturnToMainMenu;
             if (resultApplyCalibrationButton != null) resultApplyCalibrationButton.clicked += ApplyCalibrationRecommendation;
+            if (chartSaveRawButton != null) chartSaveRawButton.clicked += SaveRawChart;
+            if (chartSaveEighthButton != null) chartSaveEighthButton.clicked += SaveEighthChart;
+            if (chartSaveSixteenthButton != null) chartSaveSixteenthButton.clicked += SaveSixteenthChart;
         }
 
         private void UnbindRunControls()
@@ -656,6 +770,9 @@ private void UnbindRunControls()
             if (resultRestartButton != null) resultRestartButton.clicked -= RestartRun;
             if (resultMenuButton != null) resultMenuButton.clicked -= ReturnToMainMenu;
             if (resultApplyCalibrationButton != null) resultApplyCalibrationButton.clicked -= ApplyCalibrationRecommendation;
+            if (chartSaveRawButton != null) chartSaveRawButton.clicked -= SaveRawChart;
+            if (chartSaveEighthButton != null) chartSaveEighthButton.clicked -= SaveEighthChart;
+            if (chartSaveSixteenthButton != null) chartSaveSixteenthButton.clicked -= SaveSixteenthChart;
         }
 
         private TimingCalibrationAdvisor AdvisorFor(DrumInputSource source) =>
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs
index 6f07713..a54ad79 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs
@@ -72,7 +72,8 @@ public GameplaySessionDefinition(
             GameplayLessonId? lessonId = null,
             string songId = null,
             string chartFilePath = null,
-            string audioFilePath = null)
+            string audioFilePath = null,
+            bool isChartCreator = false)
         {
             if (!Enum.IsDefined(typeof(GameplaySessionKind), kind)) throw new ArgumentOutOfRangeException(nameof(kind));
             if (!Enum.IsDefined(typeof(GameplaySessionChart), chart)) throw new ArgumentOutOfRangeException(nameof(chart));
@@ -121,6 +122,8 @@ public GameplaySessionDefinition(
 
             if (!string.IsNullOrWhiteSpace(songId) && !GameplaySongSpeeds.IsSupported(chartPlaybackSpeed))
                 throw new ArgumentOutOfRangeException(nameof(chartPlaybackSpeed));
+            if (isChartCreator && (kind != GameplaySessionKind.FreePlay || string.IsNullOrWhiteSpace(songId)))
+                throw new ArgumentException("Chart Creator requires a selected free-play song.", nameof(isChartCreator));
 
             Kind = kind;
             Chart = chart;
@@ -142,6 +145,7 @@ public GameplaySessionDefinition(
             SongId = songId;
             ChartFilePath = chartFilePath;
             AudioFilePath = audioFilePath;
+            IsChartCreator = isChartCreator;
         }
 
         public GameplaySessionKind Kind { get; }
@@ -165,6 +169,7 @@ public GameplaySessionDefinition(
         public string SongId { get; }
         public string ChartFilePath { get; }
         public string AudioFilePath { get; }
+        public bool IsChartCreator { get; }
 
         private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
     }
@@ -243,6 +248,37 @@ public static GameplaySessionDefinition Song(
                 song.AudioPath);
         }
 
+        public static GameplaySessionDefinition ChartCreator(
+            SongLibraryEntry song,
+            GameplayPresentationTheme theme,
+            double speedMultiplier = 1.0,
+            string difficulty = null)
+        {
+            GameplaySessionDefinition source = Song(song, theme, speedMultiplier, difficulty);
+            return new GameplaySessionDefinition(
+                source.Kind,
+                source.Chart,
+                source.Difficulty,
+                source.ChartPlaybackSpeed,
+                source.Bpm,
+                source.Bars,
+                source.BeatsPerBar,
+                source.CountInBeats,
+                source.UseGeneratedSong,
+                source.Theme,
+                source.ReturnTarget,
+                source.Title,
+                source.Subtitle,
+                source.Metadata,
+                "CHART CREATOR · SUONA LIBERAMENTE: OGNI COLPO DIVENTA UNA NOTA",
+                source.ReturnButtonLabel,
+                source.LessonId,
+                source.SongId,
+                source.ChartFilePath,
+                source.AudioFilePath,
+                true);
+        }
+
         public static int SongCountInBeats(double effectiveBpm)
         {
             if (double.IsNaN(effectiveBpm) || double.IsInfinity(effectiveBpm) || effectiveBpm <= 0)
@@ -325,6 +361,16 @@ public static void SelectSong(
                 speedMultiplier,
                 difficulty));
 
+        public static void SelectChartCreator(
+            SongLibraryEntry song,
+            double speedMultiplier = 1.0,
+            string difficulty = null) =>
+            Select(GameplaySessionFactory.ChartCreator(
+                song,
+                GameplaySettingsRuntime.Current.Theme,
+                speedMultiplier,
+                difficulty));
+
         public static void SelectLesson(GameplayLessonId id, double speedMultiplier = 1.0) =>
             SelectLesson(id, speedMultiplier, GameplaySettingsRuntime.Current.Theme);
 
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
index 36e88af..9f978a7 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
@@ -66,6 +66,7 @@ public sealed class MainMenuController : MonoBehaviour
         private Button songSpeedNinetyButton;
         private Button songSpeedFullButton;
         private Button songPlayButton;
+        private Button songRecordButton;
         private Button songRefreshButton;
         private Button songFolderButton;
         private Button songBackButton;
@@ -420,6 +421,7 @@ private void TryBind()
             songSpeedNinetyButton = Required<Button>(root, "song-speed-ninety");
             songSpeedFullButton = Required<Button>(root, "song-speed-full");
             songPlayButton = Required<Button>(root, "song-play-button");
+            songRecordButton = Required<Button>(root, "song-record-button");
             songRefreshButton = Required<Button>(root, "song-refresh-button");
             songFolderButton = Required<Button>(root, "song-folder-button");
             songBackButton = Required<Button>(root, "song-back-button");
@@ -516,6 +518,7 @@ private void TryBind()
             songSpeedNinetyButton.clicked += SelectNinetySongSpeed;
             songSpeedFullButton.clicked += SelectFullSongSpeed;
             songPlayButton.clicked += StartSelectedSongFromButton;
+            songRecordButton.clicked += StartChartCreatorFromButton;
             songRefreshButton.clicked += RefreshSongLibrary;
             songFolderButton.clicked += OpenUserSongFolder;
             songBackButton.clicked += CloseSongLibrary;
@@ -624,6 +627,7 @@ private void Unbind()
             songSpeedNinetyButton.clicked -= SelectNinetySongSpeed;
             songSpeedFullButton.clicked -= SelectFullSongSpeed;
             songPlayButton.clicked -= StartSelectedSongFromButton;
+            songRecordButton.clicked -= StartChartCreatorFromButton;
             songRefreshButton.clicked -= RefreshSongLibrary;
             songFolderButton.clicked -= OpenUserSongFolder;
             songBackButton.clicked -= CloseSongLibrary;
@@ -741,6 +745,22 @@ public bool StartSelectedSong()
 
         private void StartSelectedSongFromButton() => StartSelectedSong();
 
+        public bool StartChartCreator()
+        {
+            SongLibraryEntry song = SelectedSong();
+            if (song == null || !song.IsPlayable)
+            {
+                RenderSongLibrary();
+                return false;
+            }
+
+            GameplaySessionContext.SelectChartCreator(song, selectedSongSpeed, selectedSongDifficulty);
+            Navigate(MainMenuRoutes.GameplayScene, MainMenuDestination.Play);
+            return IsNavigationPending;
+        }
+
+        private void StartChartCreatorFromButton() => StartChartCreator();
+
         public void SelectSongSpeed(double speedMultiplier)
         {
             if (!GameplaySongSpeeds.IsSupported(speedMultiplier))
@@ -1228,7 +1248,9 @@ private void RenderSongLibrary()
                     ? "AGGIUNGI UNA CARTELLA CON song.json."
                     : "ADD A FOLDER CONTAINING song.json.";
                 songPlayButton.SetEnabled(false);
+                songRecordButton.SetEnabled(false);
                 songPlayButton.text = italian ? "NESSUN BRANO" : "NO SONGS";
+                songRecordButton.text = italian ? "REGISTRA CHART" : "RECORD CHART";
                 SetSongSpeedControlsEnabled(false);
                 RenderSongSpeedSelection();
                 return;
@@ -1274,6 +1296,8 @@ private void RenderSongLibrary()
                 songPlayButton.text = italian ? "CONTENUTI NON DISPONIBILI" : "CONTENT UNAVAILABLE";
             }
             songPlayButton.SetEnabled(selected.IsPlayable);
+            songRecordButton.SetEnabled(selected.IsPlayable);
+            songRecordButton.text = italian ? "REGISTRA CHART" : "RECORD CHART";
             songRefreshButton.text = italian ? "AGGIORNA LIBRERIA" : "REFRESH LIBRARY";
             songFolderButton.text = italian ? "APRI CARTELLA BRANI" : "OPEN SONG FOLDER";
             songBackButton.text = italian ? "INDIETRO" : "BACK";
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
new file mode 100644
index 0000000..6dca706
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
@@ -0,0 +1,174 @@
+using System;
+using System.IO;
+using System.Linq;
+using HitTheKit.Core;
+using HitTheKit.Unity.Charts;
+using HitTheKit.Unity.Gameplay;
+using HitTheKit.Unity.Input;
+using NUnit.Framework;
+
+namespace HitTheKit.Unity.Tests
+{
+    public sealed class ChartCreatorTests
+    {
+        private string root;
+
+        [SetUp]
+        public void SetUp()
+        {
+            root = Path.Combine(Path.GetTempPath(), "hitthekit-chart-creator-" + Guid.NewGuid().ToString("N"));
+            Directory.CreateDirectory(root);
+        }
+
+        [TearDown]
+        public void TearDown()
+        {
+            if (Directory.Exists(root)) Directory.Delete(root, true);
+        }
+
+        [Test]
+        public void Records_only_the_song_window_and_converts_slow_practice_time_to_the_original_timeline()
+        {
+            var session = new ChartRecordingSession(20, 0.5);
+
+            Assert.That(session.Record(Input(DrumPad.Kick, -0.01)), Is.False);
+            Assert.That(session.Record(Input(DrumPad.Kick, 4.0, 100, DrumInputSource.Midi)), Is.True);
+            Assert.That(session.Record(Input(DrumPad.Snare, 20.01)), Is.False);
+            ChartRecordingDraft draft = session.Finish();
+
+            Assert.That(draft.DurationSeconds, Is.EqualTo(10));
+            Assert.That(draft.Hits, Has.Count.EqualTo(1));
+            Assert.That(draft.Hits[0].TimeSeconds, Is.EqualTo(2));
+            Assert.That(draft.Hits[0].Velocity, Is.EqualTo(100));
+            Assert.That(draft.Hits[0].Source, Is.EqualTo(DrumInputSource.Midi));
+            Assert.That(session.IgnoredCount, Is.EqualTo(2));
+            Assert.That(session.Record(Input(DrumPad.Ride, 5)), Is.False);
+        }
+
+        [Test]
+        public void Restart_discards_the_previous_take_without_leaking_state()
+        {
+            var session = new ChartRecordingSession(10);
+            session.Record(Input(DrumPad.Kick, 1));
+            session.Finish();
+
+            session.Restart();
+            session.Record(Input(DrumPad.Snare, 2));
+            ChartRecordingDraft second = session.Finish();
+
+            Assert.That(second.Hits.Select(hit => hit.Pad), Is.EqualTo(new[] { DrumPad.Snare }));
+            Assert.That(second.Hits[0].TimeSeconds, Is.EqualTo(2));
+        }
+
+        [Test]
+        public void Raw_chart_is_deterministic_sorted_and_loadable_by_the_real_schema_loader()
+        {
+            var session = new ChartRecordingSession(10);
+            session.Record(Input(DrumPad.Snare, 2));
+            session.Record(Input(DrumPad.Crash, 1));
+            session.Record(Input(DrumPad.Kick, 1));
+            ChartRecordingDraft draft = session.Finish();
+
+            string first = ChartCreatorJson.Serialize(draft, "hard", 120, ChartQuantization.None);
+            string second = ChartCreatorJson.Serialize(draft, "hard", 120, ChartQuantization.None);
+            LoadedChart loaded = new ChartLoader().Load(first, "hard");
+
+            Assert.That(second, Is.EqualTo(first));
+            Assert.That(loaded.Notes.Select(note => note.TimeSeconds), Is.EqualTo(new[] { 1d, 1d, 2d }));
+            Assert.That(loaded.Notes.Select(note => note.Pad),
+                Is.EqualTo(new[] { DrumPad.Crash, DrumPad.Kick, DrumPad.Snare }));
+        }
+
+        [Test]
+        public void Quantization_is_non_destructive_and_uses_the_selected_musical_grid()
+        {
+            var session = new ChartRecordingSession(10);
+            session.Record(Input(DrumPad.HiHat, 0.13));
+            ChartRecordingDraft draft = session.Finish();
+
+            LoadedChart raw = new ChartLoader().Load(
+                ChartCreatorJson.Serialize(draft, "easy", 120, ChartQuantization.None), "easy");
+            LoadedChart eighth = new ChartLoader().Load(
+                ChartCreatorJson.Serialize(draft, "easy", 120, ChartQuantization.EighthNote), "easy");
+            LoadedChart sixteenth = new ChartLoader().Load(
+                ChartCreatorJson.Serialize(draft, "easy", 120, ChartQuantization.SixteenthNote), "easy");
+
+            Assert.That(raw.Notes.Single().TimeSeconds, Is.EqualTo(0.13));
+            Assert.That(eighth.Notes.Single().TimeSeconds, Is.EqualTo(0.25));
+            Assert.That(sixteenth.Notes.Single().TimeSeconds, Is.EqualTo(0.125));
+            Assert.That(draft.Hits.Single().TimeSeconds, Is.EqualTo(0.13), "Quantization must not mutate the raw take.");
+        }
+
+        [Test]
+        public void Export_is_atomic_chart_only_and_discovered_as_unavailable_until_audio_is_bound()
+        {
+            var session = new ChartRecordingSession(10);
+            session.Record(Input(DrumPad.Kick, 1));
+            var metadata = new ChartCreatorMetadata(
+                "my-local-song", "My Local Song", "Local Player", "easy", 120, 5, 4);
+            DateTimeOffset created = new DateTimeOffset(2026, 8, 19, 10, 30, 0, TimeSpan.Zero);
+
+            ChartCreatorExportResult result = new ChartCreatorExporter().ExportChartOnly(
+                session.Finish(), metadata, ChartQuantization.SixteenthNote, root, created);
+            SongLibrarySnapshot snapshot = new SongLibraryDiscovery().Discover(new[]
+            {
+                new SongLibraryRoot(root, SongLibraryOrigin.UserFolder)
+            });
+
+            Assert.That(result.SongId, Is.EqualTo("my-local-song-take-20260819-103000"));
+            Assert.That(File.Exists(result.ChartPath), Is.True);
+            Assert.That(File.Exists(result.ManifestPath), Is.True);
+            Assert.That(Directory.GetFiles(result.FolderPath).Select(Path.GetFileName),
+                Is.EquivalentTo(new[] { "notes.json", "song.json" }));
+            Assert.That(Directory.GetDirectories(root, ".hitthekit-chart-*"), Is.Empty);
+            Assert.That(snapshot.Diagnostics, Is.Empty);
+            Assert.That(snapshot.Songs.Single().IsPlayable, Is.False);
+            Assert.That(snapshot.Songs.Single().AudioAvailability, Is.EqualTo(SongAudioAvailability.Missing));
+            Assert.That(snapshot.Songs.Single().ChartAvailability, Is.EqualTo(SongChartAvailability.Available));
+            Assert.That(snapshot.Songs.Single().AvailableDifficulties, Is.EqualTo(new[] { "easy" }));
+        }
+
+        [Test]
+        public void Repeated_export_never_overwrites_an_existing_take()
+        {
+            var session = new ChartRecordingSession(10);
+            session.Record(Input(DrumPad.Kick, 1));
+            ChartRecordingDraft draft = session.Finish();
+            var metadata = new ChartCreatorMetadata("song", "Song", "Player", "full", 90, 4, 4);
+            var exporter = new ChartCreatorExporter();
+            DateTimeOffset created = new DateTimeOffset(2026, 8, 19, 10, 30, 0, TimeSpan.Zero);
+
+            ChartCreatorExportResult first = exporter.ExportChartOnly(draft, metadata, ChartQuantization.None, root, created);
+            ChartCreatorExportResult second = exporter.ExportChartOnly(draft, metadata, ChartQuantization.None, root, created);
+
+            Assert.That(first.SongId, Is.EqualTo("song-take-20260819-103000"));
+            Assert.That(second.SongId, Is.EqualTo("song-take-20260819-103000-2"));
+            Assert.That(Directory.GetDirectories(root), Has.Length.EqualTo(2));
+        }
+
+        [Test]
+        public void Empty_take_is_rejected_without_publishing_a_partial_song_folder()
+        {
+            var metadata = new ChartCreatorMetadata("song", "Song", "Player", "easy", 120, 4, 4);
+            ChartRecordingDraft draft = new ChartRecordingSession(8).Finish();
+
+            InvalidOperationException error = Assert.Throws<InvalidOperationException>(() =>
+                new ChartCreatorExporter().ExportChartOnly(
+                    draft,
+                    metadata,
+                    ChartQuantization.None,
+                    root,
+                    new DateTimeOffset(2026, 8, 19, 10, 30, 0, TimeSpan.Zero)));
+
+            Assert.That(error.Message, Does.Contain("at least one hit"));
+            Assert.That(Directory.GetFileSystemEntries(root), Is.Empty);
+        }
+
+        private static DrumInputEvent Input(
+            DrumPad pad,
+            double time,
+            int velocity = 96,
+            DrumInputSource source = DrumInputSource.Keyboard) =>
+            new DrumInputEvent(pad, velocity, time, source);
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs.meta
new file mode 100644
index 0000000..6a66003
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 22aa5257193f484da02dcaa4937b086b
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
index 6395f4f..0c45f2a 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
@@ -151,6 +151,7 @@ public IEnumerator Play_opens_a_folder_discovered_setlist_with_ready_and_incompl
             Assert.That(root.Q<Label>("song-detail-title").text, Is.EqualTo("LOCAL SONG EXAMPLE"));
             Assert.That(root.Q<Label>("song-detail-artist").text, Is.EqualTo("YOUR LIBRARY"));
             Assert.That(root.Q<Button>("song-play-button").enabledSelf, Is.False);
+            Assert.That(root.Q<Button>("song-record-button").enabledSelf, Is.False);
             Assert.That(root.Q<Button>("song-speed-sixty").enabledSelf, Is.False);
             Assert.That(root.Q<VisualElement>("song-difficulty-buttons").childCount, Is.Zero);
             Assert.That(controller.StartSelectedSong(), Is.False,
@@ -159,6 +160,7 @@ public IEnumerator Play_opens_a_folder_discovered_setlist_with_ready_and_incompl
             controller.SelectSong("neon-circuit");
             Assert.That(controller.SelectedSongId, Is.EqualTo("neon-circuit"));
             Assert.That(root.Q<Button>("song-play-button").enabledSelf, Is.True);
+            Assert.That(root.Q<Button>("song-record-button").enabledSelf, Is.True);
             Assert.That(root.Q<VisualElement>("song-difficulty-buttons").Query<Button>().ToList(), Has.Count.EqualTo(1));
             Assert.That(root.Q<Button>("song-difficulty-easy"), Is.Not.Null);
             controller.SelectSongSpeed(0.6);
@@ -180,6 +182,28 @@ public IEnumerator Play_opens_a_folder_discovered_setlist_with_ready_and_incompl
             LogAssert.NoUnexpectedReceived();
         }
 
+        [UnityTest]
+        public IEnumerator Chart_creator_launches_the_real_gameplay_session_for_the_selected_playable_song()
+        {
+            MainMenuController controller = null;
+            yield return LoadMainMenu(value => controller = value);
+            controller.ShowSongLibrary();
+            controller.SelectSong("neon-circuit");
+            controller.SelectSongSpeed(0.6);
+
+            Assert.That(controller.StartChartCreator(), Is.True);
+            yield return WaitForScene(MainMenuRoutes.GameplayScene);
+
+            GameplayHighwayController gameplay = Object.FindFirstObjectByType<GameplayHighwayController>();
+            Assert.That(gameplay, Is.Not.Null);
+            Assert.That(gameplay.CurrentSession.IsChartCreator, Is.True);
+            Assert.That(gameplay.CurrentSession.SongId, Is.EqualTo("neon-circuit"));
+            Assert.That(gameplay.CurrentSession.SpeedMultiplier, Is.EqualTo(0.6));
+            Assert.That(gameplay.GetComponent<UIDocument>().rootVisualElement
+                .Q<VisualElement>("chart-creator-results"), Is.Not.Null);
+            LogAssert.NoUnexpectedReceived();
+        }
+
         [UnityTest]
         public IEnumerator Compact_song_library_keeps_rows_controls_and_actions_inside_their_panels()
         {
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
index aefaccf..db59796 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
@@ -534,6 +534,13 @@
 .result-practice { margin-top: 2px; margin-bottom: 8px; color: rgb(255, 202, 103); font-size: 12px; -unity-font-style: bold; -unity-text-align: middle-center; white-space: normal; }
 .result-calibration { min-height: 32px; color: rgb(91, 224, 255); font-size: 12px; -unity-font-style: bold; -unity-text-align: middle-center; white-space: normal; }
 .result-calibration-button { align-self: center; width: 300px; min-height: 38px; margin-top: 8px; margin-bottom: 10px; }
+.chart-creator-results { width: 100%; margin-top: 8px; padding: 12px; background-color: rgba(4, 22, 30, 0.96); border-width: 1px; border-color: rgba(65, 219, 255, 0.72); border-radius: 6px; }
+.chart-creator-eyebrow { color: rgb(91, 224, 255); }
+.chart-creator-summary { margin-top: 6px; color: white; font-size: 19px; -unity-font-style: bold; -unity-text-align: middle-center; }
+.chart-creator-copy { margin-top: 6px; color: rgb(171, 196, 211); font-size: 10px; white-space: normal; -unity-text-align: middle-center; }
+.chart-creator-actions { margin-top: 10px; flex-direction: row; justify-content: center; }
+.chart-save-button { width: 170px; min-height: 38px; margin: 0 4px; }
+.chart-creator-status { min-height: 20px; margin-top: 8px; color: rgb(78, 221, 137); font-size: 10px; -unity-font-style: bold; white-space: normal; -unity-text-align: middle-center; }
 .gameplay--high-contrast .highway-shell,
 .gameplay--high-contrast .results-dialog,
 .gameplay--high-contrast .run-dialog { border-color: white; background-color: rgba(0, 0, 0, 0.97); }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
index 52aff34..e422b29 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
@@ -121,6 +121,17 @@
                 <ui:Label name="result-practice" text="FOCUS: COMPLETA UNA SESSIONE" class="result-practice" />
                 <ui:Label name="result-calibration" text="CALIBRAZIONE: SERVONO 8 COLPI VALIDI" class="result-calibration" />
                 <ui:Button name="result-apply-calibration" text="APPLICA CALIBRAZIONE" class="run-secondary-button result-calibration-button" />
+                <ui:VisualElement name="chart-creator-results" class="chart-creator-results" style="display: none;">
+                    <ui:Label text="REVISIONE TAKE" class="eyebrow chart-creator-eyebrow" />
+                    <ui:Label name="chart-creator-summary" text="0 COLPI REGISTRATI" class="chart-creator-summary" />
+                    <ui:Label text="L'audio non viene copiato. Scegli quanto allineare i colpi alla griglia e salva una bozza in Documents/HTKSongs." class="chart-creator-copy" />
+                    <ui:VisualElement class="chart-creator-actions">
+                        <ui:Button name="chart-save-raw" text="SALVA RAW" class="run-secondary-button chart-save-button" />
+                        <ui:Button name="chart-save-eighth" text="SALVA 1/8" class="run-secondary-button chart-save-button" />
+                        <ui:Button name="chart-save-sixteenth" text="SALVA 1/16" class="run-primary-button chart-save-button" />
+                    </ui:VisualElement>
+                    <ui:Label name="chart-creator-status" class="chart-creator-status" />
+                </ui:VisualElement>
                 <ui:VisualElement class="result-actions">
                     <ui:Button name="result-restart-button" text="SUONA ANCORA" class="run-primary-button" />
                     <ui:Button name="result-menu-button" text="MENU PRINCIPALE" class="run-secondary-button" />
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
index bb84666..8d6721f 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
@@ -950,7 +950,9 @@
 .song-detail-readiness { margin-top: 10px; padding: 7px 8px; flex-shrink: 0; color: rgb(78, 221, 137); background-color: rgba(6, 45, 28, 0.74); border-left-width: 3px; border-left-color: rgb(78, 221, 137); font-size: 9px; -unity-font-style: bold; white-space: normal; }
 .song-detail-readiness--missing { color: rgb(244, 182, 86); background-color: rgba(52, 29, 8, 0.78); border-left-color: rgb(231, 151, 56); }
 .song-play-actions { flex-shrink: 0; margin-top: 9px; padding-top: 9px; background-color: rgb(8, 13, 18); border-top-width: 1px; border-top-color: rgba(76, 130, 160, 0.48); }
+.song-primary-actions { flex-direction: row; }
 .song-play-button {
+    flex-grow: 1;
     height: 50px;
     min-height: 50px;
     border-width: 2px;
@@ -962,6 +964,23 @@
     -unity-font-style: bold;
     letter-spacing: 0.7px;
 }
+.song-record-button {
+    width: 22%;
+    min-width: 80px;
+    height: 50px;
+    min-height: 50px;
+    margin-left: 5px;
+    border-width: 1px;
+    border-color: rgb(236, 167, 73);
+    border-radius: 5px;
+    background-color: rgb(49, 28, 10);
+    color: rgb(255, 206, 130);
+    font-size: 8px;
+    -unity-font-style: bold;
+    letter-spacing: 0.5px;
+}
+.song-record-button:hover, .song-record-button:focus { background-color: rgb(101, 54, 12); border-color: white; }
+.song-record-button:disabled { opacity: 0.42; }
 .song-play-button:hover, .song-play-button:focus { background-color: rgb(8, 132, 171); border-color: white; scale: 1.025; }
 .song-play-button:disabled { opacity: 0.42; scale: 1; }
 .song-play-hint { margin-top: 7px; color: rgb(115, 182, 203); font-size: 8px; -unity-font-style: bold; -unity-text-align: middle-center; }
@@ -1018,5 +1037,6 @@
 .main-menu--short .song-speed-button { height: 27px; min-height: 27px; }
 .main-menu--short .song-detail-readiness { margin-top: 7px; padding: 6px; }
 .main-menu--short .song-play-actions { margin-top: 6px; padding-top: 6px; }
-.main-menu--short .song-play-button { height: 43px; min-height: 43px; }
+.main-menu--short .song-play-button,
+.main-menu--short .song-record-button { height: 43px; min-height: 43px; }
 .main-menu--short .song-library-footer { height: 50px; min-height: 50px; margin-top: 7px; }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
index 96bb300..01e1a48 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
@@ -113,7 +113,10 @@
                             <ui:Label name="song-detail-readiness" class="song-detail-readiness" />
                         </ui:ScrollView>
                         <ui:VisualElement class="song-play-actions">
-                            <ui:Button name="song-play-button" text="SUONA ORA" class="song-play-button" />
+                            <ui:VisualElement class="song-primary-actions">
+                                <ui:Button name="song-play-button" text="SUONA ORA" class="song-play-button" />
+                                <ui:Button name="song-record-button" text="REGISTRA CHART" class="song-record-button" />
+                            </ui:VisualElement>
                             <ui:Label text="INVIO O DOPPIO KICK" class="song-play-hint" />
                         </ui:VisualElement>
                     </ui:VisualElement>

From 798c6c21a2661ae67ad70b4acda55f927be6769b Mon Sep 17 00:00:00 2001
From: Baron Luca <baron_luca@hotmail.it>
Date: Wed, 19 Aug 2026 14:05:17 +0200
Subject: [PATCH 2/5] feat(songs): add portable htksong packages

---
 docs/development/chart-creator.md             |  21 +-
 docs/development/song-library.md              |  16 +
 .../Runtime/Gameplay/ChartCreator.cs          |  21 +-
 .../Gameplay/GameplayHighwayController.cs     |   7 +-
 .../Runtime/Gameplay/HtkSongPackage.cs        | 329 ++++++++++++++++++
 .../Runtime/Gameplay/HtkSongPackage.cs.meta   |  11 +
 .../Runtime/MainMenu/MainMenuController.cs    |  43 ++-
 .../Tests/EditMode/ChartCreatorTests.cs       |  13 +
 .../Tests/EditMode/HtkSongPackageTests.cs     | 201 +++++++++++
 .../EditMode/HtkSongPackageTests.cs.meta      |  11 +
 .../UI/Gameplay/GameplayHighway.uxml          |   2 +-
 11 files changed, 664 insertions(+), 11 deletions(-)
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs.meta
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs.meta

diff --git a/docs/development/chart-creator.md b/docs/development/chart-creator.md
index e6dccec..c81680e 100644
--- a/docs/development/chart-creator.md
+++ b/docs/development/chart-creator.md
@@ -28,12 +28,31 @@ The exporter creates a new, never-overwritten folder under
 - `song.json`;
 - `notes.json`.
 
+It also creates one portable `<song-id>.htksong` file alongside the folder.
+The package is a ZIP-compatible, chart-only container with exactly three
+entries:
+
+- `htksong-version` (`1`);
+- `song.json`;
+- `notes.json`.
+
+To transfer a take, copy only the `.htksong` file into
+`Documents/HTKSongs` on the other computer and refresh the Song Library. The
+game validates and atomically imports it. Existing song folders are never
+overwritten.
+
 The publish is atomic and both documents are parsed by the production loaders
-before the folder becomes visible. The manifest declares chart availability but
+before the folder or package becomes visible. The manifest declares chart availability but
 keeps audio as `missing`. Chart Creator never copies, embeds, downloads, or
 redistributes the source audio. To play or share the take, the user must add an
 audio file they are entitled to use and update the local binding explicitly.
 
+Import is fail-closed. Unknown/archive entries, audio declarations, symbolic
+links, duplicate names, unsupported versions, malformed JSON, invalid charts,
+oversized data and path traversal are rejected before extraction. Version 1 is
+intentionally chart-only; adding optional distributable audio requires a future
+explicit package version and rights-aware UX.
+
 The exported title is marked `Recorded Take` and the difficulty hint says that
 the performance must be reviewed before sharing. This is a captured performance,
 not a claim of authoritative transcription.
diff --git a/docs/development/song-library.md b/docs/development/song-library.md
index 10485f6..4804771 100644
--- a/docs/development/song-library.md
+++ b/docs/development/song-library.md
@@ -94,3 +94,19 @@ machine-specific path into bundled `song.json`.
 The refresh button performs an explicit rescan. Discovery does not watch the
 filesystem continuously, allocate every frame, or access folders outside the
 two configured roots.
+
+## Portable `.htksong` chart packages
+
+Chart Creator writes a portable chart-only package next to each recorded take.
+Copy a `.htksong` file directly into `~/Documents/HTKSongs` and select
+**Refresh library**. Before normal folder discovery, the game validates the
+container and atomically installs its `song.json` and `notes.json` into a folder
+named after the validated song ID. The package remains in place so it can be
+copied to another computer; subsequent refreshes are idempotent.
+
+Package schema version 1 contains no audio and rejects any audio declaration or
+extra archive entry. Imports are bounded to 5 MiB, reject links, duplicate or
+case-colliding names, malformed ZIP/JSON/chart data, unsupported versions and
+path traversal, and never replace an existing song folder. An imported chart is
+therefore visible but unavailable until the player explicitly supplies audio
+they are entitled to use through the ordinary local song binding.
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
index d6d2883..1640668 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
@@ -263,17 +263,24 @@ public ProjectedHit(double timeSeconds, DrumPad pad, int recordingIndex)
 
     public sealed class ChartCreatorExportResult
     {
-        internal ChartCreatorExportResult(string songId, string folderPath, string chartPath, string manifestPath)
+        internal ChartCreatorExportResult(
+            string songId,
+            string folderPath,
+            string chartPath,
+            string manifestPath,
+            string packagePath)
         {
             SongId = songId;
             FolderPath = folderPath;
             ChartPath = chartPath;
             ManifestPath = manifestPath;
+            PackagePath = packagePath;
         }
         public string SongId { get; }
         public string FolderPath { get; }
         public string ChartPath { get; }
         public string ManifestPath { get; }
+        public string PackagePath { get; }
     }
 
     public sealed class ChartCreatorExporter
@@ -300,8 +307,10 @@ public ChartCreatorExportResult ExportChartOnly(
             string baseId = $"{prefix}-take-{createdAtUtc:yyyyMMdd-HHmmss}";
             string songId = UniqueSongId(root, baseId);
             string destination = Path.Combine(root, songId);
+            string packagePath = Path.Combine(root, songId + HtkSongPackageService.Extension);
             string temporary = Path.Combine(root, $".hitthekit-chart-{Guid.NewGuid():N}");
             Directory.CreateDirectory(temporary);
+            bool destinationPublished = false;
             try
             {
                 string chartJson = ChartCreatorJson.Serialize(draft, metadata.Difficulty, metadata.Bpm, quantization);
@@ -314,15 +323,19 @@ public ChartCreatorExportResult ExportChartOnly(
                 new ChartLoader().Load(chartJson, metadata.Difficulty);
                 new SongLibraryDiscovery().Parse(File.ReadAllText(manifestPath), temporary, SongLibraryOrigin.UserFolder);
                 Directory.Move(temporary, destination);
+                destinationPublished = true;
+                new HtkSongPackageService().CreateChartOnlyPackage(destination, packagePath);
                 return new ChartCreatorExportResult(
                     songId,
                     destination,
                     Path.Combine(destination, "notes.json"),
-                    Path.Combine(destination, "song.json"));
+                    Path.Combine(destination, "song.json"),
+                    packagePath);
             }
             catch
             {
                 if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                if (destinationPublished && Directory.Exists(destination)) Directory.Delete(destination, true);
                 throw;
             }
         }
@@ -331,7 +344,9 @@ private static string UniqueSongId(string root, string baseId)
         {
             string value = baseId;
             int suffix = 2;
-            while (Directory.Exists(Path.Combine(root, value))) value = $"{baseId}-{suffix++}";
+            while (Directory.Exists(Path.Combine(root, value)) ||
+                   File.Exists(Path.Combine(root, value + HtkSongPackageService.Extension)))
+                value = $"{baseId}-{suffix++}";
             ChartCreatorMetadata.ValidateIdentifier(value, nameof(baseId));
             return value;
         }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
index eb4ed72..5d6e499 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
+using System.IO;
 using HitTheKit.Core;
 using HitTheKit.Unity.Audio;
 using HitTheKit.Unity.Charts;
@@ -124,6 +125,7 @@ public sealed class GameplayHighwayController : MonoBehaviour
         public double CurrentAttemptPracticeSeconds => practiceTimer.CurrentAttemptSeconds;
         public int RecordedChartHitCount => chartRecording?.HitCount ?? chartDraft?.Hits.Count ?? 0;
         public string LastChartExportPath { get; private set; }
+        public string LastChartPackagePath { get; private set; }
 
         private void Awake()
         {
@@ -508,6 +510,7 @@ public void RestartRun()
             resultRecorded = false;
             chartDraft = null;
             LastChartExportPath = null;
+            LastChartPackagePath = null;
             chartRecording?.Restart();
             scoreTracker.Reset();
             keyboardCalibration.Reset();
@@ -643,8 +646,10 @@ public ChartCreatorExportResult SaveChartRecording(ChartQuantization quantizatio
                 SongLibraryRuntime.UserRoot,
                 DateTimeOffset.UtcNow);
             LastChartExportPath = result.FolderPath;
+            LastChartPackagePath = result.PackagePath;
             if (chartCreatorStatusLabel != null)
-                chartCreatorStatusLabel.text = $"SALVATO · {result.SongId} · AGGIUNGI SOLO AUDIO AUTORIZZATO";
+                chartCreatorStatusLabel.text =
+                    $"SALVATO · {Path.GetFileName(result.PackagePath)} · COPIA IL PACCHETTO SU UN ALTRO MAC";
             return result;
         }
 
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs
new file mode 100644
index 0000000..1e2d44b
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs
@@ -0,0 +1,329 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.IO;
+using System.IO.Compression;
+using System.Text;
+
+namespace HitTheKit.Unity.Gameplay
+{
+    public enum HtkSongImportStatus
+    {
+        Imported,
+        AlreadyInstalled
+    }
+
+    public sealed class HtkSongImportResult
+    {
+        internal HtkSongImportResult(string songId, string folderPath, HtkSongImportStatus status)
+        {
+            SongId = songId;
+            FolderPath = folderPath;
+            Status = status;
+        }
+
+        public string SongId { get; }
+        public string FolderPath { get; }
+        public HtkSongImportStatus Status { get; }
+    }
+
+    public sealed class HtkSongInboxResult
+    {
+        internal HtkSongInboxResult(IReadOnlyList<string> importedSongIds, IReadOnlyList<string> diagnostics)
+        {
+            ImportedSongIds = importedSongIds;
+            Diagnostics = diagnostics;
+        }
+
+        public IReadOnlyList<string> ImportedSongIds { get; }
+        public IReadOnlyList<string> Diagnostics { get; }
+    }
+
+    public sealed class HtkSongPackageException : Exception
+    {
+        public HtkSongPackageException(string message) : base(message) { }
+        public HtkSongPackageException(string message, Exception innerException) : base(message, innerException) { }
+    }
+
+    public sealed class HtkSongPackageService
+    {
+        public const int PackageVersion = 1;
+        public const string Extension = ".htksong";
+        public const string VersionEntryName = "htksong-version";
+        public const string ManifestEntryName = "song.json";
+        public const string ChartEntryName = "notes.json";
+        public const long MaximumPackageBytes = 5L * 1024 * 1024;
+        public const long MaximumManifestBytes = 64L * 1024;
+        public const long MaximumChartBytes = 4L * 1024 * 1024;
+
+        private static readonly UTF8Encoding Utf8WithoutBom = new UTF8Encoding(false, true);
+        private static readonly DateTimeOffset StableEntryTimestamp =
+            new DateTimeOffset(1980, 1, 1, 0, 0, 0, TimeSpan.Zero);
+
+        public string CreateChartOnlyPackage(string songFolder, string packagePath)
+        {
+            if (string.IsNullOrWhiteSpace(songFolder))
+                throw new ArgumentException("Song folder is required.", nameof(songFolder));
+            ValidatePackagePath(packagePath);
+
+            string folder = Path.GetFullPath(songFolder);
+            if (!Directory.Exists(folder)) throw new HtkSongPackageException("The song folder does not exist.");
+            if (IsLink(folder)) throw new HtkSongPackageException("The song folder cannot be a symbolic link.");
+
+            string manifestPath = Path.Combine(folder, ManifestEntryName);
+            string chartPath = Path.Combine(folder, ChartEntryName);
+            ValidateSourceFile(manifestPath, MaximumManifestBytes, ManifestEntryName);
+            ValidateSourceFile(chartPath, MaximumChartBytes, ChartEntryName);
+            SongLibraryEntry song = ValidateChartOnlySong(folder, File.ReadAllText(manifestPath));
+            string expectedPackageName = song.Id + Extension;
+            if (!string.Equals(Path.GetFileName(packagePath), expectedPackageName, StringComparison.Ordinal))
+                throw new HtkSongPackageException($"Package filename must be '{expectedPackageName}'.");
+
+            string destination = Path.GetFullPath(packagePath);
+            string parent = Path.GetDirectoryName(destination);
+            if (string.IsNullOrEmpty(parent)) throw new HtkSongPackageException("Package destination is invalid.");
+            Directory.CreateDirectory(parent);
+            if (File.Exists(destination)) throw new HtkSongPackageException("A package with this song ID already exists.");
+
+            string temporary = Path.Combine(parent, $".hitthekit-package-{Guid.NewGuid():N}.tmp");
+            try
+            {
+                using (var stream = new FileStream(temporary, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None))
+                using (var archive = new ZipArchive(stream, ZipArchiveMode.Create, false, Utf8WithoutBom))
+                {
+                    WriteEntry(archive, VersionEntryName, Encoding.ASCII.GetBytes(PackageVersion + "\n"));
+                    WriteEntry(archive, ManifestEntryName, File.ReadAllBytes(manifestPath));
+                    WriteEntry(archive, ChartEntryName, File.ReadAllBytes(chartPath));
+                }
+
+                ValidatePackageFile(temporary);
+                File.Move(temporary, destination);
+                return destination;
+            }
+            catch (HtkSongPackageException)
+            {
+                if (File.Exists(temporary)) File.Delete(temporary);
+                throw;
+            }
+            catch (Exception exception)
+            {
+                if (File.Exists(temporary)) File.Delete(temporary);
+                throw new HtkSongPackageException("The chart package could not be created.", exception);
+            }
+        }
+
+        public HtkSongImportResult ImportChartOnlyPackage(string packagePath, string libraryRoot)
+        {
+            ValidatePackagePath(packagePath);
+            if (string.IsNullOrWhiteSpace(libraryRoot))
+                throw new ArgumentException("Song-library root is required.", nameof(libraryRoot));
+
+            string package = Path.GetFullPath(packagePath);
+            string root = Path.GetFullPath(libraryRoot);
+            if (!File.Exists(package)) throw new HtkSongPackageException("The .htksong package does not exist.");
+            if (IsLink(package)) throw new HtkSongPackageException("A .htksong package cannot be a symbolic link.");
+            Directory.CreateDirectory(root);
+
+            PackagePayload payload = ReadPackage(package);
+            string temporary = Path.Combine(root, $".hitthekit-import-{Guid.NewGuid():N}");
+            Directory.CreateDirectory(temporary);
+            try
+            {
+                File.WriteAllBytes(Path.Combine(temporary, ManifestEntryName), payload.Manifest);
+                File.WriteAllBytes(Path.Combine(temporary, ChartEntryName), payload.Chart);
+                SongLibraryEntry song = ValidateChartOnlySong(
+                    temporary,
+                    Utf8WithoutBom.GetString(payload.Manifest));
+                string destination = Path.Combine(root, song.Id);
+
+                if (Directory.Exists(destination))
+                {
+                    Directory.Delete(temporary, true);
+                    return new HtkSongImportResult(song.Id, destination, HtkSongImportStatus.AlreadyInstalled);
+                }
+
+                Directory.Move(temporary, destination);
+                return new HtkSongImportResult(song.Id, destination, HtkSongImportStatus.Imported);
+            }
+            catch (HtkSongPackageException)
+            {
+                if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                throw;
+            }
+            catch (SongLibraryLoadException exception)
+            {
+                if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                throw new HtkSongPackageException("The package contains an invalid song manifest or chart.", exception);
+            }
+            catch (Exception exception)
+            {
+                if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                throw new HtkSongPackageException("The .htksong package could not be imported.", exception);
+            }
+        }
+
+        public HtkSongInboxResult ImportInbox(string libraryRoot)
+        {
+            if (string.IsNullOrWhiteSpace(libraryRoot))
+                throw new ArgumentException("Song-library root is required.", nameof(libraryRoot));
+            string root = Path.GetFullPath(libraryRoot);
+            Directory.CreateDirectory(root);
+
+            string[] packages = Directory.GetFiles(root, "*" + Extension, SearchOption.TopDirectoryOnly);
+            Array.Sort(packages, StringComparer.Ordinal);
+            var imported = new List<string>();
+            var diagnostics = new List<string>();
+            foreach (string package in packages)
+            {
+                try
+                {
+                    HtkSongImportResult result = ImportChartOnlyPackage(package, root);
+                    if (result.Status == HtkSongImportStatus.Imported) imported.Add(result.SongId);
+                }
+                catch (HtkSongPackageException exception)
+                {
+                    diagnostics.Add($"Package '{Path.GetFileName(package)}' was ignored: {exception.Message}");
+                }
+                catch (Exception exception)
+                {
+                    diagnostics.Add(
+                        $"Package '{Path.GetFileName(package)}' could not be read ({exception.GetType().Name}).");
+                }
+            }
+
+            return new HtkSongInboxResult(
+                new ReadOnlyCollection<string>(imported),
+                new ReadOnlyCollection<string>(diagnostics));
+        }
+
+        private static PackagePayload ReadPackage(string packagePath)
+        {
+            ValidatePackageFile(packagePath);
+            try
+            {
+                using (var stream = new FileStream(packagePath, FileMode.Open, FileAccess.Read, FileShare.Read))
+                using (var archive = new ZipArchive(stream, ZipArchiveMode.Read, false, Utf8WithoutBom))
+                {
+                    if (archive.Entries.Count != 3)
+                        throw new HtkSongPackageException("A chart-only package must contain exactly three entries.");
+                    var entries = new Dictionary<string, ZipArchiveEntry>(StringComparer.Ordinal);
+                    var caseInsensitiveNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+                    foreach (ZipArchiveEntry entry in archive.Entries)
+                    {
+                        if (!caseInsensitiveNames.Add(entry.FullName))
+                            throw new HtkSongPackageException("Package entry names must be unique case-insensitively.");
+                        if (!IsAllowedEntry(entry.FullName))
+                            throw new HtkSongPackageException("A chart-only package contains an unsupported entry.");
+                        entries.Add(entry.FullName, entry);
+                    }
+
+                    byte[] version = ReadEntry(entries[VersionEntryName], 16, VersionEntryName);
+                    if (!string.Equals(Encoding.ASCII.GetString(version), PackageVersion + "\n", StringComparison.Ordinal))
+                        throw new HtkSongPackageException("Unsupported .htksong package version.");
+                    byte[] manifest = ReadEntry(entries[ManifestEntryName], MaximumManifestBytes, ManifestEntryName);
+                    byte[] chart = ReadEntry(entries[ChartEntryName], MaximumChartBytes, ChartEntryName);
+                    return new PackagePayload(manifest, chart);
+                }
+            }
+            catch (HtkSongPackageException)
+            {
+                throw;
+            }
+            catch (Exception exception)
+            {
+                throw new HtkSongPackageException("The file is not a valid .htksong archive.", exception);
+            }
+        }
+
+        private static SongLibraryEntry ValidateChartOnlySong(string folder, string manifestJson)
+        {
+            SongLibraryEntry song = new SongLibraryDiscovery().Parse(
+                manifestJson,
+                folder,
+                SongLibraryOrigin.UserFolder);
+            if (song.AudioAvailability != SongAudioAvailability.Missing || song.AudioPath != null)
+                throw new HtkSongPackageException("Chart-only packages cannot contain or declare audio.");
+            if (song.ChartAvailability != SongChartAvailability.Available ||
+                !string.Equals(Path.GetFileName(song.ChartPath), ChartEntryName, StringComparison.Ordinal))
+                throw new HtkSongPackageException("A chart-only package must declare notes.json as available.");
+            return song;
+        }
+
+        private static byte[] ReadEntry(ZipArchiveEntry entry, long maximumBytes, string name)
+        {
+            if (entry.Length <= 0 || entry.Length > maximumBytes)
+                throw new HtkSongPackageException($"{name} exceeds the allowed package size.");
+            if (entry.CompressedLength < 0 || entry.CompressedLength > MaximumPackageBytes)
+                throw new HtkSongPackageException($"{name} has an invalid compressed size.");
+
+            using (Stream source = entry.Open())
+            using (var destination = new MemoryStream((int)entry.Length))
+            {
+                var buffer = new byte[8192];
+                long total = 0;
+                while (true)
+                {
+                    int read = source.Read(buffer, 0, buffer.Length);
+                    if (read == 0) break;
+                    total += read;
+                    if (total > maximumBytes)
+                        throw new HtkSongPackageException($"{name} exceeds the allowed package size.");
+                    destination.Write(buffer, 0, read);
+                }
+                if (total != entry.Length)
+                    throw new HtkSongPackageException($"{name} has an inconsistent uncompressed size.");
+                return destination.ToArray();
+            }
+        }
+
+        private static void WriteEntry(ZipArchive archive, string name, byte[] content)
+        {
+            ZipArchiveEntry entry = archive.CreateEntry(name, CompressionLevel.Optimal);
+            entry.LastWriteTime = StableEntryTimestamp;
+            using (Stream stream = entry.Open()) stream.Write(content, 0, content.Length);
+        }
+
+        private static bool IsAllowedEntry(string name) =>
+            string.Equals(name, VersionEntryName, StringComparison.Ordinal) ||
+            string.Equals(name, ManifestEntryName, StringComparison.Ordinal) ||
+            string.Equals(name, ChartEntryName, StringComparison.Ordinal);
+
+        private static void ValidatePackagePath(string path)
+        {
+            if (string.IsNullOrWhiteSpace(path))
+                throw new ArgumentException("Package path is required.", nameof(path));
+            if (!string.Equals(Path.GetExtension(path), Extension, StringComparison.OrdinalIgnoreCase))
+                throw new HtkSongPackageException("Chart packages must use the .htksong extension.");
+        }
+
+        private static void ValidatePackageFile(string path)
+        {
+            var info = new FileInfo(path);
+            if (!info.Exists || info.Length <= 0 || info.Length > MaximumPackageBytes)
+                throw new HtkSongPackageException("A .htksong package must be between 1 byte and 5 MiB.");
+        }
+
+        private static void ValidateSourceFile(string path, long maximumBytes, string name)
+        {
+            var info = new FileInfo(path);
+            if (!info.Exists || info.Length <= 0 || info.Length > maximumBytes)
+                throw new HtkSongPackageException($"{name} is missing or exceeds the allowed size.");
+            if (IsLink(path)) throw new HtkSongPackageException($"{name} cannot be a symbolic link.");
+        }
+
+        private static bool IsLink(string path) =>
+            (File.GetAttributes(path) & FileAttributes.ReparsePoint) != 0;
+
+        private sealed class PackagePayload
+        {
+            public PackagePayload(byte[] manifest, byte[] chart)
+            {
+                Manifest = manifest;
+                Chart = chart;
+            }
+
+            public byte[] Manifest { get; }
+            public byte[] Chart { get; }
+        }
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs.meta
new file mode 100644
index 0000000..b16ae3c
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/HtkSongPackage.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 6b8d024e2b1d4dbbb724f4169bccf8a6
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
index 9f978a7..8d8eeb3 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
@@ -147,6 +147,7 @@ public sealed class MainMenuController : MonoBehaviour
         private int learnOpenedFrame = -1;
         private int playOpenedFrame = -1;
         private SongLibrarySnapshot songLibrary;
+        private HtkSongInboxResult packageInbox;
         private string selectedSongId;
         private string selectedSongDifficulty;
         private double selectedSongSpeed = 1.0;
@@ -702,11 +703,28 @@ private void HandleSetup()
 
         public void RefreshSongLibrary()
         {
+            try
+            {
+                packageInbox = new HtkSongPackageService().ImportInbox(SongLibraryRuntime.UserRoot);
+            }
+            catch (Exception exception)
+            {
+                packageInbox = null;
+                Debug.LogWarning($"Could not scan .htksong packages ({exception.GetType().Name}).", this);
+            }
             songLibrary = SongLibraryRuntime.Discover();
+            string importedSongId = packageInbox?.ImportedSongIds.Count > 0
+                ? packageInbox.ImportedSongIds[packageInbox.ImportedSongIds.Count - 1]
+                : null;
             if (songLibrary.Songs.Count == 0)
             {
                 selectedSongId = null;
             }
+            else if (!string.IsNullOrEmpty(importedSongId) &&
+                     songLibrary.Songs.Any(song => string.Equals(song.Id, importedSongId, StringComparison.Ordinal)))
+            {
+                selectedSongId = importedSongId;
+            }
             else if (string.IsNullOrEmpty(selectedSongId) ||
                      songLibrary.Songs.All(song => !string.Equals(song.Id, selectedSongId, StringComparison.Ordinal)))
             {
@@ -1301,11 +1319,26 @@ private void RenderSongLibrary()
             songRefreshButton.text = italian ? "AGGIORNA LIBRERIA" : "REFRESH LIBRARY";
             songFolderButton.text = italian ? "APRI CARTELLA BRANI" : "OPEN SONG FOLDER";
             songBackButton.text = italian ? "INDIETRO" : "BACK";
-            songLibraryDiagnostic.text = songLibrary.Diagnostics.Count == 0
-                ? (italian
-                    ? "CATALOGO: song.json · BINDING LOCALI OPZIONALI"
-                    : "CATALOG: song.json · OPTIONAL LOCAL BINDINGS")
-                : $"{songLibrary.Diagnostics.Count} " + (italian ? "CARTELLE IGNORATE" : "FOLDERS IGNORED");
+            if (packageInbox?.ImportedSongIds.Count > 0)
+            {
+                songLibraryDiagnostic.text = italian
+                    ? $"PACCHETTO .htksong IMPORTATO · {packageInbox.ImportedSongIds.Count}"
+                    : $".htksong PACKAGE IMPORTED · {packageInbox.ImportedSongIds.Count}";
+            }
+            else if (packageInbox?.Diagnostics.Count > 0)
+            {
+                songLibraryDiagnostic.text = italian
+                    ? $"{packageInbox.Diagnostics.Count} PACCHETTI .htksong IGNORATI"
+                    : $"{packageInbox.Diagnostics.Count} .htksong PACKAGES IGNORED";
+            }
+            else
+            {
+                songLibraryDiagnostic.text = songLibrary.Diagnostics.Count == 0
+                    ? (italian
+                        ? "CATALOGO: CARTELLE + PACCHETTI .htksong"
+                        : "CATALOG: FOLDERS + .htksong PACKAGES")
+                    : $"{songLibrary.Diagnostics.Count} " + (italian ? "CARTELLE IGNORATE" : "FOLDERS IGNORED");
+            }
         }
 
         private void SetSongSpeedControlsEnabled(bool enabled)
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
index 6dca706..821bbe1 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
@@ -1,5 +1,6 @@
 using System;
 using System.IO;
+using System.IO.Compression;
 using System.Linq;
 using HitTheKit.Core;
 using HitTheKit.Unity.Charts;
@@ -118,8 +119,19 @@ public void Export_is_atomic_chart_only_and_discovered_as_unavailable_until_audi
             Assert.That(result.SongId, Is.EqualTo("my-local-song-take-20260819-103000"));
             Assert.That(File.Exists(result.ChartPath), Is.True);
             Assert.That(File.Exists(result.ManifestPath), Is.True);
+            Assert.That(File.Exists(result.PackagePath), Is.True);
             Assert.That(Directory.GetFiles(result.FolderPath).Select(Path.GetFileName),
                 Is.EquivalentTo(new[] { "notes.json", "song.json" }));
+            using (var packageStream = File.OpenRead(result.PackagePath))
+            using (var package = new ZipArchive(packageStream, ZipArchiveMode.Read))
+            {
+                Assert.That(package.Entries.Select(entry => entry.FullName), Is.EqualTo(new[]
+                {
+                    HtkSongPackageService.VersionEntryName,
+                    HtkSongPackageService.ManifestEntryName,
+                    HtkSongPackageService.ChartEntryName
+                }));
+            }
             Assert.That(Directory.GetDirectories(root, ".hitthekit-chart-*"), Is.Empty);
             Assert.That(snapshot.Diagnostics, Is.Empty);
             Assert.That(snapshot.Songs.Single().IsPlayable, Is.False);
@@ -144,6 +156,7 @@ public void Repeated_export_never_overwrites_an_existing_take()
             Assert.That(first.SongId, Is.EqualTo("song-take-20260819-103000"));
             Assert.That(second.SongId, Is.EqualTo("song-take-20260819-103000-2"));
             Assert.That(Directory.GetDirectories(root), Has.Length.EqualTo(2));
+            Assert.That(Directory.GetFiles(root, "*.htksong"), Has.Length.EqualTo(2));
         }
 
         [Test]
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs
new file mode 100644
index 0000000..7032682
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs
@@ -0,0 +1,201 @@
+using System;
+using System.IO;
+using System.IO.Compression;
+using System.Linq;
+using System.Text;
+using HitTheKit.Core;
+using HitTheKit.Unity.Gameplay;
+using HitTheKit.Unity.Input;
+using NUnit.Framework;
+
+namespace HitTheKit.Unity.Tests
+{
+    public sealed class HtkSongPackageTests
+    {
+        private string root;
+        private string exportRoot;
+        private string importRoot;
+
+        [SetUp]
+        public void SetUp()
+        {
+            root = Path.Combine(Path.GetTempPath(), "hitthekit-package-tests-" + Guid.NewGuid().ToString("N"));
+            exportRoot = Path.Combine(root, "export");
+            importRoot = Path.Combine(root, "import");
+            Directory.CreateDirectory(exportRoot);
+            Directory.CreateDirectory(importRoot);
+        }
+
+        [TearDown]
+        public void TearDown()
+        {
+            if (Directory.Exists(root)) Directory.Delete(root, true);
+        }
+
+        [Test]
+        public void Chart_only_package_round_trip_imports_the_real_song_formats_without_audio()
+        {
+            ChartCreatorExportResult exported = ExportTake();
+            string incoming = Path.Combine(importRoot, Path.GetFileName(exported.PackagePath));
+            File.Copy(exported.PackagePath, incoming);
+
+            HtkSongImportResult imported = new HtkSongPackageService().ImportChartOnlyPackage(incoming, importRoot);
+            SongLibrarySnapshot library = new SongLibraryDiscovery().Discover(new[]
+            {
+                new SongLibraryRoot(importRoot, SongLibraryOrigin.UserFolder)
+            });
+
+            Assert.That(imported.Status, Is.EqualTo(HtkSongImportStatus.Imported));
+            Assert.That(imported.SongId, Is.EqualTo(exported.SongId));
+            Assert.That(Directory.GetFiles(imported.FolderPath).Select(Path.GetFileName),
+                Is.EquivalentTo(new[] { "song.json", "notes.json" }));
+            Assert.That(library.Diagnostics, Is.Empty);
+            Assert.That(library.Songs.Single().AudioAvailability, Is.EqualTo(SongAudioAvailability.Missing));
+            Assert.That(library.Songs.Single().ChartAvailability, Is.EqualTo(SongChartAvailability.Available));
+            Assert.That(library.Songs.Single().IsPlayable, Is.False);
+            Assert.That(File.ReadAllText(Path.Combine(imported.FolderPath, "notes.json")),
+                Is.EqualTo(File.ReadAllText(exported.ChartPath)));
+        }
+
+        [Test]
+        public void Inbox_import_is_deterministic_idempotent_and_preserves_the_portable_file()
+        {
+            ChartCreatorExportResult exported = ExportTake();
+            string incoming = Path.Combine(importRoot, Path.GetFileName(exported.PackagePath));
+            File.Copy(exported.PackagePath, incoming);
+            var service = new HtkSongPackageService();
+
+            HtkSongInboxResult first = service.ImportInbox(importRoot);
+            HtkSongInboxResult second = service.ImportInbox(importRoot);
+
+            Assert.That(first.ImportedSongIds, Is.EqualTo(new[] { exported.SongId }));
+            Assert.That(first.Diagnostics, Is.Empty);
+            Assert.That(second.ImportedSongIds, Is.Empty);
+            Assert.That(second.Diagnostics, Is.Empty);
+            Assert.That(File.Exists(incoming), Is.True, "The transferable package must remain available.");
+            Assert.That(Directory.GetDirectories(importRoot, ".hitthekit-import-*"), Is.Empty);
+        }
+
+        [Test]
+        public void Existing_song_folder_is_never_overwritten_by_an_import()
+        {
+            ChartCreatorExportResult exported = ExportTake();
+            string incoming = Path.Combine(importRoot, Path.GetFileName(exported.PackagePath));
+            File.Copy(exported.PackagePath, incoming);
+            var service = new HtkSongPackageService();
+            HtkSongImportResult first = service.ImportChartOnlyPackage(incoming, importRoot);
+            string sentinel = Path.Combine(first.FolderPath, "local-change.txt");
+            File.WriteAllText(sentinel, "keep me");
+
+            HtkSongImportResult second = service.ImportChartOnlyPackage(incoming, importRoot);
+
+            Assert.That(second.Status, Is.EqualTo(HtkSongImportStatus.AlreadyInstalled));
+            Assert.That(File.ReadAllText(sentinel), Is.EqualTo("keep me"));
+        }
+
+        [Test]
+        public void Package_with_path_traversal_or_unknown_entry_is_rejected_before_extraction()
+        {
+            string package = Path.Combine(importRoot, "unsafe.htksong");
+            WriteArchive(package,
+                (HtkSongPackageService.VersionEntryName, "1\n"),
+                (HtkSongPackageService.ManifestEntryName, ValidManifest("unsafe")),
+                ("../notes.json", ValidChart()));
+
+            HtkSongPackageException error = Assert.Throws<HtkSongPackageException>(() =>
+                new HtkSongPackageService().ImportChartOnlyPackage(package, importRoot));
+
+            Assert.That(error.Message, Does.Contain("unsupported entry"));
+            Assert.That(File.Exists(Path.Combine(root, "notes.json")), Is.False);
+            Assert.That(Directory.Exists(Path.Combine(importRoot, "unsafe")), Is.False);
+        }
+
+        [Test]
+        public void Package_with_case_insensitive_duplicate_entries_is_rejected()
+        {
+            string package = Path.Combine(importRoot, "duplicate.htksong");
+            WriteArchive(package,
+                (HtkSongPackageService.VersionEntryName, "1\n"),
+                (HtkSongPackageService.ManifestEntryName, ValidManifest("duplicate")),
+                ("SONG.JSON", ValidManifest("duplicate")));
+
+            HtkSongPackageException error = Assert.Throws<HtkSongPackageException>(() =>
+                new HtkSongPackageService().ImportChartOnlyPackage(package, importRoot));
+
+            Assert.That(error.Message, Does.Contain("unique case-insensitively"));
+            Assert.That(Directory.Exists(Path.Combine(importRoot, "duplicate")), Is.False);
+        }
+
+        [Test]
+        public void Chart_only_package_cannot_smuggle_or_declare_audio()
+        {
+            string package = Path.Combine(importRoot, "audio.htksong");
+            WriteArchive(package,
+                (HtkSongPackageService.VersionEntryName, "1\n"),
+                (HtkSongPackageService.ManifestEntryName, ValidManifest("audio")
+                    .Replace("\"audioAvailability\":\"missing\"",
+                        "\"audioAvailability\":\"available\",\"audioFile\":\"song.wav\"")),
+                (HtkSongPackageService.ChartEntryName, ValidChart()));
+
+            HtkSongPackageException error = Assert.Throws<HtkSongPackageException>(() =>
+                new HtkSongPackageService().ImportChartOnlyPackage(package, importRoot));
+
+            Assert.That(error.Message, Does.Contain("cannot contain or declare audio"));
+            Assert.That(Directory.Exists(Path.Combine(importRoot, "audio")), Is.False);
+        }
+
+        [Test]
+        public void Wrong_version_and_malformed_archives_are_fail_closed_and_reported_by_the_inbox()
+        {
+            string wrongVersion = Path.Combine(importRoot, "wrong-version.htksong");
+            WriteArchive(wrongVersion,
+                (HtkSongPackageService.VersionEntryName, "2\n"),
+                (HtkSongPackageService.ManifestEntryName, ValidManifest("wrong-version")),
+                (HtkSongPackageService.ChartEntryName, ValidChart()));
+            File.WriteAllText(Path.Combine(importRoot, "malformed.htksong"), "not a zip");
+
+            HtkSongInboxResult result = new HtkSongPackageService().ImportInbox(importRoot);
+
+            Assert.That(result.ImportedSongIds, Is.Empty);
+            Assert.That(result.Diagnostics, Has.Count.EqualTo(2));
+            Assert.That(Directory.GetDirectories(importRoot), Is.Empty);
+        }
+
+        private ChartCreatorExportResult ExportTake()
+        {
+            var session = new ChartRecordingSession(8);
+            session.Record(new DrumInputEvent(DrumPad.Kick, 100, 1, DrumInputSource.Test));
+            var metadata = new ChartCreatorMetadata("portable-song", "Portable Song", "Local Player", "easy", 120, 4, 4);
+            return new ChartCreatorExporter().ExportChartOnly(
+                session.Finish(),
+                metadata,
+                ChartQuantization.None,
+                exportRoot,
+                new DateTimeOffset(2026, 8, 19, 12, 0, 0, TimeSpan.Zero));
+        }
+
+        private static string ValidManifest(string id) =>
+            "{\"schemaVersion\":1," +
+            $"\"id\":\"{id}\",\"title\":\"Song\",\"artist\":\"Local Player\"," +
+            "\"bpm\":120,\"bars\":4,\"beatsPerBar\":4," +
+            "\"audioAvailability\":\"missing\"," +
+            "\"chartAvailability\":\"available\",\"chartFile\":\"notes.json\"}";
+
+        private static string ValidChart() =>
+            "{\"version\":1,\"offsetSeconds\":0,\"difficulties\":{" +
+            "\"easy\":[{\"time\":1,\"pad\":\"kick\"}]}}";
+
+        private static void WriteArchive(string path, params (string Name, string Content)[] entries)
+        {
+            using (var stream = new FileStream(path, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None))
+            using (var archive = new ZipArchive(stream, ZipArchiveMode.Create))
+            {
+                foreach ((string name, string content) in entries)
+                {
+                    ZipArchiveEntry entry = archive.CreateEntry(name);
+                    using (var writer = new StreamWriter(entry.Open(), new UTF8Encoding(false))) writer.Write(content);
+                }
+            }
+        }
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs.meta
new file mode 100644
index 0000000..5e14eb1
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 4bd25cc652474edaa997bd12a51e4cc3
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
index e422b29..86fdbd8 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
@@ -124,7 +124,7 @@
                 <ui:VisualElement name="chart-creator-results" class="chart-creator-results" style="display: none;">
                     <ui:Label text="REVISIONE TAKE" class="eyebrow chart-creator-eyebrow" />
                     <ui:Label name="chart-creator-summary" text="0 COLPI REGISTRATI" class="chart-creator-summary" />
-                    <ui:Label text="L'audio non viene copiato. Scegli quanto allineare i colpi alla griglia e salva una bozza in Documents/HTKSongs." class="chart-creator-copy" />
+                    <ui:Label text="L'audio non viene copiato. Salva la chart e usa il file .htksong per trasferirla su un altro computer." class="chart-creator-copy" />
                     <ui:VisualElement class="chart-creator-actions">
                         <ui:Button name="chart-save-raw" text="SALVA RAW" class="run-secondary-button chart-save-button" />
                         <ui:Button name="chart-save-eighth" text="SALVA 1/8" class="run-secondary-button chart-save-button" />

From 82dad46ff4d8813c9dd960b46452c290efb5a2af Mon Sep 17 00:00:00 2001
From: Baron Luca <baron_luca@hotmail.it>
Date: Wed, 19 Aug 2026 14:45:41 +0200
Subject: [PATCH 3/5] feat(charts): import local audio for authoring

---
 docs/development/chart-creator.md             |  29 ++-
 docs/development/song-library.md              |  14 +
 .../Runtime/Gameplay/ChartAuthoringAudio.cs   | 240 ++++++++++++++++++
 .../Gameplay/ChartAuthoringAudio.cs.meta      |  11 +
 .../Runtime/Gameplay/ChartCreator.cs          |  51 +++-
 .../Gameplay/GameplayHighwayController.cs     |  14 +-
 .../Gameplay/GameplaySessionCoordinator.cs    |  12 +
 .../Gameplay/GameplaySessionDefinition.cs     |  49 +++-
 .../HitTheKit/Runtime/Gameplay/SongLibrary.cs |   4 +
 .../Runtime/MainMenu/MainMenuController.cs    | 151 ++++++++++-
 .../EditMode/ChartAuthoringAudioTests.cs      | 159 ++++++++++++
 .../EditMode/ChartAuthoringAudioTests.cs.meta |  11 +
 .../Tests/PlayMode/MainMenuPlayModeTests.cs   |  92 +++++++
 .../Assets/HitTheKit/UI/MainMenu/MainMenu.uss |  42 +++
 .../HitTheKit/UI/MainMenu/MainMenu.uxml       |  39 +++
 15 files changed, 885 insertions(+), 33 deletions(-)
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs.meta
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs.meta

diff --git a/docs/development/chart-creator.md b/docs/development/chart-creator.md
index c81680e..8503785 100644
--- a/docs/development/chart-creator.md
+++ b/docs/development/chart-creator.md
@@ -7,9 +7,14 @@ timeline.
 
 ## Workflow
 
-1. Add or select a playable song in the Song Library.
-2. Choose its difficulty and practice speed.
-3. Select **Record chart**.
+1. Select **Import audio & create** in the Song Library and choose a local WAV
+   or OGG file, or select an existing playable song.
+2. For new audio, enter title, artist, verified BPM, bar count and beats per bar.
+   HitTheKit copies the selected audio into a private local authoring folder; it
+   never modifies the source file.
+3. Choose practice speed and select **Record chart**. A new audio-only source
+   starts with a real empty schema-v1 timeline; an existing song keeps its
+   current chart only as a playback reference.
 4. Play during the normal count-in and backing track. Hits before song time zero
    or beyond the declared song duration are ignored.
 5. At the result screen, review the captured-hit count and save the raw timing,
@@ -42,10 +47,11 @@ game validates and atomically imports it. Existing song folders are never
 overwritten.
 
 The publish is atomic and both documents are parsed by the production loaders
-before the folder or package becomes visible. The manifest declares chart availability but
-keeps audio as `missing`. Chart Creator never copies, embeds, downloads, or
-redistributes the source audio. To play or share the take, the user must add an
-audio file they are entitled to use and update the local binding explicitly.
+before the folder or package becomes visible. When the recording used a local
+WAV/OGG source, the private exported folder receives its own local audio copy and
+is immediately playable. The `.htksong` manifest still declares audio as
+`missing`: Chart Creator never embeds, downloads, or redistributes source audio
+in the portable package. A recipient supplies their own authorized local copy.
 
 Import is fail-closed. Unknown/archive entries, audio declarations, symbolic
 links, duplicate names, unsupported versions, malformed JSON, invalid charts,
@@ -59,10 +65,13 @@ not a claim of authoritative transcription.
 
 ## Current foundation limits
 
-- A playable Song Library entry is required; audio import/file-picker UI is not
-  part of this first foundation.
 - Editing individual notes is not yet available. Raw/1/8/1/16 save choices are
   the initial review tools.
 - The schema currently stores pad and time. Velocity and articulation remain in
   the in-memory take but schema v1 does not serialize them.
-- Exported takes are intentionally non-playable until authorized audio is bound.
+- The native picker currently targets macOS. WAV and OGG are supported; MP3 is
+  intentionally rejected by the production loader.
+- The author must enter BPM, bars and meter explicitly. Unknown timing never
+  receives a hidden default.
+- Portable packages remain chart-only; imported packages require an authorized
+  local audio binding on the receiving computer.
diff --git a/docs/development/song-library.md b/docs/development/song-library.md
index 4804771..9e5c304 100644
--- a/docs/development/song-library.md
+++ b/docs/development/song-library.md
@@ -95,6 +95,20 @@ The refresh button performs an explicit rescan. Discovery does not watch the
 filesystem continuously, allocate every frame, or access folders outside the
 two configured roots.
 
+## Local audio authoring
+
+The Song Library's **Import audio & create** action opens the macOS file picker
+for WAV/OGG content. After the player supplies title, artist and verified timing
+metadata, the importer copies the selected file into a new, never-overwritten
+folder under `~/Documents/HTKSongs`. The source file is not changed and its
+absolute path is not persisted in `song.json`.
+
+The resulting entry is intentionally audio-only: it is not playable as a normal
+song, but it can start Chart Creator with the existing DSP clock and an empty
+timeline. Once a take is saved, the local folder contains authorized audio plus
+the new chart and is playable immediately. Its sibling `.htksong` remains
+chart-only for safe transfer.
+
 ## Portable `.htksong` chart packages
 
 Chart Creator writes a portable chart-only package next to each recorded take.
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs
new file mode 100644
index 0000000..00b0d11
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs
@@ -0,0 +1,240 @@
+using System;
+using System.Diagnostics;
+using System.Globalization;
+using System.IO;
+using System.Text;
+using UnityEngine;
+
+namespace HitTheKit.Unity.Gameplay
+{
+    public sealed class ChartAuthoringAudioRequest
+    {
+        public ChartAuthoringAudioRequest(
+            string sourceAudioPath,
+            string title,
+            string artist,
+            double bpm,
+            int bars,
+            int beatsPerBar)
+        {
+            if (string.IsNullOrWhiteSpace(sourceAudioPath))
+                throw new ArgumentException("An audio file is required.", nameof(sourceAudioPath));
+            if (string.IsNullOrWhiteSpace(title)) throw new ArgumentException("Title is required.", nameof(title));
+            if (string.IsNullOrWhiteSpace(artist)) throw new ArgumentException("Artist is required.", nameof(artist));
+            if (!IsFinite(bpm) || bpm <= 0 || bpm > 400) throw new ArgumentOutOfRangeException(nameof(bpm));
+            if (bars <= 0 || bars > 10000) throw new ArgumentOutOfRangeException(nameof(bars));
+            if (beatsPerBar <= 0 || beatsPerBar > 32) throw new ArgumentOutOfRangeException(nameof(beatsPerBar));
+
+            SourceAudioPath = Path.GetFullPath(sourceAudioPath);
+            Title = title.Trim();
+            Artist = artist.Trim();
+            Bpm = bpm;
+            Bars = bars;
+            BeatsPerBar = beatsPerBar;
+        }
+
+        public string SourceAudioPath { get; }
+        public string Title { get; }
+        public string Artist { get; }
+        public double Bpm { get; }
+        public int Bars { get; }
+        public int BeatsPerBar { get; }
+
+        private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+    }
+
+    public sealed class ChartAuthoringAudioImportResult
+    {
+        internal ChartAuthoringAudioImportResult(SongLibraryEntry song, string sourcePath)
+        {
+            Song = song;
+            SourcePath = sourcePath;
+        }
+
+        public SongLibraryEntry Song { get; }
+        public string SourcePath { get; }
+    }
+
+    public sealed class ChartAuthoringAudioImportException : Exception
+    {
+        public ChartAuthoringAudioImportException(string message) : base(message) { }
+        public ChartAuthoringAudioImportException(string message, Exception innerException) : base(message, innerException) { }
+    }
+
+    public sealed class ChartAuthoringAudioImporter
+    {
+        public const long MaximumAudioBytes = 1024L * 1024 * 1024;
+        private static readonly UTF8Encoding Utf8WithoutBom = new UTF8Encoding(false);
+
+        public ChartAuthoringAudioImportResult Import(
+            ChartAuthoringAudioRequest request,
+            string libraryRoot,
+            DateTimeOffset createdAtUtc)
+        {
+            if (request == null) throw new ArgumentNullException(nameof(request));
+            if (string.IsNullOrWhiteSpace(libraryRoot))
+                throw new ArgumentException("Song-library root is required.", nameof(libraryRoot));
+            if (createdAtUtc.Offset != TimeSpan.Zero)
+                throw new ArgumentException("Creation time must be UTC.", nameof(createdAtUtc));
+
+            string source = ValidateSource(request.SourceAudioPath);
+            string root = Path.GetFullPath(libraryRoot);
+            Directory.CreateDirectory(root);
+            string baseId = BuildId(request.Artist, request.Title, createdAtUtc);
+            string songId = UniqueSongId(root, baseId);
+            string destination = Path.Combine(root, songId);
+            string temporary = Path.Combine(root, $".hitthekit-audio-{Guid.NewGuid():N}");
+            string audioFileName = "source-audio" + Path.GetExtension(source).ToLowerInvariant();
+            Directory.CreateDirectory(temporary);
+
+            try
+            {
+                string copiedAudio = Path.Combine(temporary, audioFileName);
+                File.Copy(source, copiedAudio, false);
+                string manifest = Manifest(songId, request, audioFileName);
+                File.WriteAllText(Path.Combine(temporary, SongLibraryDiscovery.ManifestFileName), manifest, Utf8WithoutBom);
+                SongLibraryEntry validated = new SongLibraryDiscovery().Parse(
+                    manifest,
+                    temporary,
+                    SongLibraryOrigin.UserFolder);
+                if (!validated.CanAuthorChart || validated.IsPlayable)
+                    throw new ChartAuthoringAudioImportException("The imported audio did not produce a valid authoring source.");
+
+                Directory.Move(temporary, destination);
+                SongLibraryEntry published = new SongLibraryDiscovery().Parse(
+                    File.ReadAllText(Path.Combine(destination, SongLibraryDiscovery.ManifestFileName)),
+                    destination,
+                    SongLibraryOrigin.UserFolder);
+                return new ChartAuthoringAudioImportResult(published, source);
+            }
+            catch (ChartAuthoringAudioImportException)
+            {
+                if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                throw;
+            }
+            catch (Exception exception)
+            {
+                if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                throw new ChartAuthoringAudioImportException("The selected audio could not be imported.", exception);
+            }
+        }
+
+        public static string ValidateSource(string sourceAudioPath)
+        {
+            if (string.IsNullOrWhiteSpace(sourceAudioPath))
+                throw new ChartAuthoringAudioImportException("Select a WAV or OGG audio file.");
+            string source = Path.GetFullPath(sourceAudioPath);
+            var info = new FileInfo(source);
+            if (!info.Exists || info.Length <= 0 || info.Length > MaximumAudioBytes)
+                throw new ChartAuthoringAudioImportException("Audio must be between 1 byte and 1 GiB.");
+            if ((File.GetAttributes(source) & FileAttributes.ReparsePoint) != 0)
+                throw new ChartAuthoringAudioImportException("The selected audio cannot be a symbolic link.");
+            string extension = Path.GetExtension(source);
+            if (!string.Equals(extension, ".wav", StringComparison.OrdinalIgnoreCase) &&
+                !string.Equals(extension, ".ogg", StringComparison.OrdinalIgnoreCase))
+                throw new ChartAuthoringAudioImportException("Chart Creator supports WAV and OGG audio.");
+            return source;
+        }
+
+        private static string UniqueSongId(string root, string baseId)
+        {
+            string candidate = baseId;
+            int suffix = 2;
+            while (Directory.Exists(Path.Combine(root, candidate)) ||
+                   File.Exists(Path.Combine(root, candidate + HtkSongPackageService.Extension)))
+                candidate = $"{baseId}-{suffix++}";
+            ChartCreatorMetadata.ValidateIdentifier(candidate, nameof(baseId));
+            return candidate;
+        }
+
+        private static string BuildId(string artist, string title, DateTimeOffset createdAtUtc)
+        {
+            string text = (artist + "-" + title).Normalize(NormalizationForm.FormD);
+            var id = new StringBuilder(64);
+            bool separator = false;
+            for (int index = 0; index < text.Length && id.Length < 48; index++)
+            {
+                char value = char.ToLowerInvariant(text[index]);
+                if (value >= 'a' && value <= 'z' || value >= '0' && value <= '9')
+                {
+                    id.Append(value);
+                    separator = false;
+                }
+                else if (id.Length > 0 && !separator)
+                {
+                    id.Append('-');
+                    separator = true;
+                }
+            }
+            string prefix = id.ToString().Trim('-');
+            if (prefix.Length == 0) prefix = "local-song";
+            return $"{prefix}-authoring-{createdAtUtc:yyyyMMdd-HHmmss}";
+        }
+
+        private static string Manifest(
+            string songId,
+            ChartAuthoringAudioRequest request,
+            string audioFileName)
+        {
+            return "{\n" +
+                   "  \"schemaVersion\": 1,\n" +
+                   $"  \"id\": \"{Escape(songId)}\",\n" +
+                   $"  \"title\": \"{Escape(request.Title)}\",\n" +
+                   $"  \"artist\": \"{Escape(request.Artist)}\",\n" +
+                   $"  \"bpm\": {request.Bpm.ToString("0.#########", CultureInfo.InvariantCulture)},\n" +
+                   $"  \"bars\": {request.Bars},\n" +
+                   $"  \"beatsPerBar\": {request.BeatsPerBar},\n" +
+                   "  \"difficultyHint\": \"New local chart\",\n" +
+                   "  \"sortOrder\": 0,\n" +
+                   "  \"audioAvailability\": \"available\",\n" +
+                   $"  \"audioFile\": \"{Escape(audioFileName)}\",\n" +
+                   "  \"chartAvailability\": \"unavailable\"\n" +
+                   "}\n";
+        }
+
+        private static string Escape(string value) => value
+            .Replace("\\", "\\\\")
+            .Replace("\"", "\\\"")
+            .Replace("\r", "\\r")
+            .Replace("\n", "\\n");
+    }
+
+    public interface IChartAuthoringAudioPicker
+    {
+        string PickAudioFile();
+    }
+
+    public sealed class MacOsChartAuthoringAudioPicker : IChartAuthoringAudioPicker
+    {
+        public string PickAudioFile()
+        {
+#if UNITY_STANDALONE_OSX || UNITY_EDITOR_OSX
+            const string script =
+                "const app = Application.currentApplication(); " +
+                "app.includeStandardAdditions = true; " +
+                "const chosen = app.chooseFile({withPrompt: 'Choose a WAV or OGG backing track'}); " +
+                "Path(chosen).toString();";
+            var start = new ProcessStartInfo
+            {
+                FileName = "/usr/bin/osascript",
+                Arguments = "-l JavaScript -e \"" +
+                            script.Replace("\\", "\\\\").Replace("\"", "\\\"") + "\"",
+                UseShellExecute = false,
+                RedirectStandardOutput = true,
+                RedirectStandardError = true,
+                CreateNoWindow = true
+            };
+            using (Process process = Process.Start(start))
+            {
+                if (process == null) throw new InvalidOperationException("The macOS audio picker could not start.");
+                string output = process.StandardOutput.ReadToEnd();
+                process.StandardError.ReadToEnd();
+                process.WaitForExit();
+                return process.ExitCode == 0 ? output.Trim() : null;
+            }
+#else
+            throw new PlatformNotSupportedException("The native audio picker currently supports macOS.");
+#endif
+        }
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs.meta
new file mode 100644
index 0000000..f8f807d
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartAuthoringAudio.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 3e8f45ac662e4b50b9fd231315fd1419
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
index 1640668..15793de 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
@@ -268,19 +268,23 @@ internal ChartCreatorExportResult(
             string folderPath,
             string chartPath,
             string manifestPath,
-            string packagePath)
+            string packagePath,
+            string localAudioPath)
         {
             SongId = songId;
             FolderPath = folderPath;
             ChartPath = chartPath;
             ManifestPath = manifestPath;
             PackagePath = packagePath;
+            LocalAudioPath = localAudioPath;
         }
         public string SongId { get; }
         public string FolderPath { get; }
         public string ChartPath { get; }
         public string ManifestPath { get; }
         public string PackagePath { get; }
+        public string LocalAudioPath { get; }
+        public bool IsLocallyPlayable => !string.IsNullOrWhiteSpace(LocalAudioPath);
     }
 
     public sealed class ChartCreatorExporter
@@ -292,7 +296,8 @@ public ChartCreatorExportResult ExportChartOnly(
             ChartCreatorMetadata metadata,
             ChartQuantization quantization,
             string libraryRoot,
-            DateTimeOffset createdAtUtc)
+            DateTimeOffset createdAtUtc,
+            string sourceAudioPath = null)
         {
             if (draft == null) throw new ArgumentNullException(nameof(draft));
             if (draft.Hits.Count == 0)
@@ -310,32 +315,52 @@ public ChartCreatorExportResult ExportChartOnly(
             string packagePath = Path.Combine(root, songId + HtkSongPackageService.Extension);
             string temporary = Path.Combine(root, $".hitthekit-chart-{Guid.NewGuid():N}");
             Directory.CreateDirectory(temporary);
-            bool destinationPublished = false;
+            bool packagePublished = false;
             try
             {
                 string chartJson = ChartCreatorJson.Serialize(draft, metadata.Difficulty, metadata.Bpm, quantization);
                 string chartPath = Path.Combine(temporary, "notes.json");
                 string manifestPath = Path.Combine(temporary, "song.json");
                 File.WriteAllText(chartPath, chartJson, Utf8WithoutBom);
-                File.WriteAllText(manifestPath, Manifest(songId, metadata), Utf8WithoutBom);
+                File.WriteAllText(manifestPath, Manifest(songId, metadata, null), Utf8WithoutBom);
 
-                // Validate both public formats before the atomic publish into HTKSongs.
+                // First validate and publish the shareable chart-only package. Local audio is
+                // added only to the private folder afterwards and never enters .htksong v1.
                 new ChartLoader().Load(chartJson, metadata.Difficulty);
                 new SongLibraryDiscovery().Parse(File.ReadAllText(manifestPath), temporary, SongLibraryOrigin.UserFolder);
+                new HtkSongPackageService().CreateChartOnlyPackage(temporary, packagePath);
+                packagePublished = true;
+
+                string localAudioPath = null;
+                if (!string.IsNullOrWhiteSpace(sourceAudioPath))
+                {
+                    string source = ChartAuthoringAudioImporter.ValidateSource(sourceAudioPath);
+                    string audioFileName = "source-audio" + Path.GetExtension(source).ToLowerInvariant();
+                    localAudioPath = Path.Combine(temporary, audioFileName);
+                    File.Copy(source, localAudioPath, false);
+                    File.WriteAllText(manifestPath, Manifest(songId, metadata, audioFileName), Utf8WithoutBom);
+                    SongLibraryEntry local = new SongLibraryDiscovery().Parse(
+                        File.ReadAllText(manifestPath),
+                        temporary,
+                        SongLibraryOrigin.UserFolder);
+                    if (!local.IsPlayable)
+                        throw new InvalidOperationException("The local recorded take did not become playable.");
+                }
+
                 Directory.Move(temporary, destination);
-                destinationPublished = true;
-                new HtkSongPackageService().CreateChartOnlyPackage(destination, packagePath);
                 return new ChartCreatorExportResult(
                     songId,
                     destination,
                     Path.Combine(destination, "notes.json"),
                     Path.Combine(destination, "song.json"),
-                    packagePath);
+                    packagePath,
+                    localAudioPath == null ? null : Path.Combine(destination, Path.GetFileName(localAudioPath)));
             }
             catch
             {
                 if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
-                if (destinationPublished && Directory.Exists(destination)) Directory.Delete(destination, true);
+                if (Directory.Exists(destination)) Directory.Delete(destination, true);
+                if (packagePublished && File.Exists(packagePath)) File.Delete(packagePath);
                 throw;
             }
         }
@@ -351,8 +376,12 @@ private static string UniqueSongId(string root, string baseId)
             return value;
         }
 
-        private static string Manifest(string songId, ChartCreatorMetadata metadata)
+        private static string Manifest(string songId, ChartCreatorMetadata metadata, string audioFileName)
         {
+            string audio = string.IsNullOrWhiteSpace(audioFileName)
+                ? "  \"audioAvailability\": \"missing\",\n"
+                : "  \"audioAvailability\": \"available\",\n" +
+                  $"  \"audioFile\": \"{Escape(audioFileName)}\",\n";
             return "{\n" +
                    "  \"schemaVersion\": 1,\n" +
                    $"  \"id\": \"{Escape(songId)}\",\n" +
@@ -363,7 +392,7 @@ private static string Manifest(string songId, ChartCreatorMetadata metadata)
                    $"  \"beatsPerBar\": {metadata.BeatsPerBar},\n" +
                    "  \"difficultyHint\": \"Recorded performance · review before sharing\",\n" +
                    "  \"sortOrder\": 0,\n" +
-                   "  \"audioAvailability\": \"missing\",\n" +
+                   audio +
                    "  \"chartAvailability\": \"available\",\n" +
                    "  \"chartFile\": \"notes.json\"\n" +
                    "}\n";
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
index 5d6e499..e52762f 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
@@ -426,6 +426,13 @@ private void HandleInputProcessed(DrumInputEvent input, HitResult result)
             }
             currentInputLabel.text = $"{GameplayHighwayLanes.Find(input.Pad).Label}  ·  VELOCITY {input.Velocity}{timing}";
 
+            if (CurrentSession.IsChartCreator)
+            {
+                PlayDrum(input.Pad, input.Velocity);
+                SetJudgment("REC", "judgment--perfect");
+                return;
+            }
+
             GameplayAudioFeedbackDecision audioDecision = GameplayAudioFeedbackPolicy.ForInput(input, result);
             if (audioDecision.PlayDrum) PlayDrum(input.Pad, input.Velocity);
             if (audioDecision.PlayMistake) PlayMistake();
@@ -644,12 +651,15 @@ public ChartCreatorExportResult SaveChartRecording(ChartQuantization quantizatio
                 metadata,
                 quantization,
                 SongLibraryRuntime.UserRoot,
-                DateTimeOffset.UtcNow);
+                DateTimeOffset.UtcNow,
+                CurrentSession.AudioFilePath);
             LastChartExportPath = result.FolderPath;
             LastChartPackagePath = result.PackagePath;
             if (chartCreatorStatusLabel != null)
                 chartCreatorStatusLabel.text =
-                    $"SALVATO · {Path.GetFileName(result.PackagePath)} · COPIA IL PACCHETTO SU UN ALTRO MAC";
+                    result.IsLocallyPlayable
+                        ? $"SALVATO E PRONTO · {Path.GetFileName(result.PackagePath)} · AUDIO SOLO LOCALE"
+                        : $"SALVATO · {Path.GetFileName(result.PackagePath)} · AGGIUNGI AUDIO LOCALE";
             return result;
         }
 
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionCoordinator.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionCoordinator.cs
index 660a702..71c6226 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionCoordinator.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionCoordinator.cs
@@ -17,6 +17,7 @@ public sealed class GameplaySessionCoordinator : MonoBehaviour
         [SerializeField] private TextAsset firstGrooveChart;
         private TextAsset generatedLessonChart;
         private TextAsset runtimeChartAsset;
+        private TextAsset authoringChartAsset;
 
         public GameplaySessionDefinition Session { get; private set; }
         public bool IsConfigured { get; private set; }
@@ -73,6 +74,12 @@ private TextAsset ChartFor(GameplaySessionChart chart)
                     runtimeChartAsset = new TextAsset(File.ReadAllText(Session.ChartFilePath));
                     runtimeChartAsset.name = $"Imported song {Session.SongId}";
                     return runtimeChartAsset;
+                case GameplaySessionChart.AuthoringEmpty:
+                    authoringChartAsset = new TextAsset(
+                        "{\n  \"version\": 1,\n  \"offsetSeconds\": 0,\n  \"difficulties\": {\n    \"" +
+                        Session.Difficulty + "\": []\n  }\n}\n");
+                    authoringChartAsset.name = $"New chart for {Session.SongId}";
+                    return authoringChartAsset;
                 default: throw new ArgumentOutOfRangeException(nameof(chart));
             }
         }
@@ -89,6 +96,11 @@ private void OnDestroy()
                 Destroy(runtimeChartAsset);
                 runtimeChartAsset = null;
             }
+            if (authoringChartAsset != null)
+            {
+                Destroy(authoringChartAsset);
+                authoringChartAsset = null;
+            }
         }
     }
 }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs
index a54ad79..1e96803 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplaySessionDefinition.cs
@@ -40,7 +40,8 @@ public enum GameplaySessionChart
         Timekeeper,
         FirstGroove,
         SchoolLesson,
-        ExternalFile
+        ExternalFile,
+        AuthoringEmpty
     }
 
     public enum GameplayReturnTarget
@@ -115,6 +116,17 @@ public GameplaySessionDefinition(
                 if (string.IsNullOrWhiteSpace(audioFilePath))
                     throw new ArgumentException("External songs require an audio file.", nameof(audioFilePath));
             }
+            else if (chart == GameplaySessionChart.AuthoringEmpty)
+            {
+                if (!isChartCreator || kind != GameplaySessionKind.FreePlay)
+                    throw new ArgumentException("An empty authoring timeline requires Chart Creator.", nameof(chart));
+                if (string.IsNullOrWhiteSpace(songId))
+                    throw new ArgumentException("Chart authoring requires a song ID.", nameof(songId));
+                if (!string.IsNullOrEmpty(chartFilePath))
+                    throw new ArgumentException("A new chart must not reference an existing chart file.", nameof(chartFilePath));
+                if (string.IsNullOrWhiteSpace(audioFilePath))
+                    throw new ArgumentException("Chart authoring requires imported audio.", nameof(audioFilePath));
+            }
             else if (!string.IsNullOrEmpty(chartFilePath) || !string.IsNullOrEmpty(audioFilePath))
             {
                 throw new ArgumentException("Only external songs can reference chart or audio files.");
@@ -254,6 +266,41 @@ public static GameplaySessionDefinition ChartCreator(
             double speedMultiplier = 1.0,
             string difficulty = null)
         {
+            if (song == null) throw new ArgumentNullException(nameof(song));
+            if (!GameplaySongSpeeds.IsSupported(speedMultiplier))
+                throw new ArgumentOutOfRangeException(nameof(speedMultiplier));
+            if (!song.IsPlayable)
+            {
+                if (!song.CanAuthorChart)
+                    throw new InvalidOperationException($"Song '{song.Id}' has no valid local audio for chart authoring.");
+                string authoringDifficulty = string.IsNullOrWhiteSpace(difficulty) ? "easy" : difficulty;
+                if (!ContainsDifficulty(HitTheKit.Unity.Charts.ChartLoader.SupportedDifficulties, authoringDifficulty))
+                    throw new ArgumentOutOfRangeException(nameof(difficulty));
+                double effectiveBpm = song.Bpm.Value * speedMultiplier;
+                return new GameplaySessionDefinition(
+                    GameplaySessionKind.FreePlay,
+                    GameplaySessionChart.AuthoringEmpty,
+                    authoringDifficulty,
+                    speedMultiplier,
+                    effectiveBpm,
+                    song.Bars.Value,
+                    song.BeatsPerBar.Value,
+                    SongCountInBeats(effectiveBpm),
+                    false,
+                    theme,
+                    GameplayReturnTarget.SongLibrary,
+                    song.Title.ToUpperInvariant(),
+                    song.Artist.ToUpperInvariant(),
+                    $"{song.Artist.ToUpperInvariant()} · NUOVA CHART · {effectiveBpm:0.#} BPM · {speedMultiplier:0.##}×",
+                    "CHART CREATOR · ASCOLTA L'AUDIO E REGISTRA OGNI COLPO",
+                    "TORNA AI BRANI",
+                    null,
+                    song.Id,
+                    null,
+                    song.AudioPath,
+                    true);
+            }
+
             GameplaySessionDefinition source = Song(song, theme, speedMultiplier, difficulty);
             return new GameplaySessionDefinition(
                 source.Kind,
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs
index f3a26df..8472536 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs
@@ -103,6 +103,10 @@ internal SongLibraryEntry(
         public IReadOnlyList<string> AvailableDifficulties { get; }
         public IReadOnlyList<string> MissingFiles { get; }
         public bool IsPlayable => Availability == SongLibraryAvailability.Ready;
+        public bool CanAuthorChart =>
+            AudioAvailability == SongAudioAvailability.Available &&
+            !string.IsNullOrWhiteSpace(AudioPath) &&
+            Bpm.HasValue && Bars.HasValue && BeatsPerBar.HasValue;
     }
 
     public sealed class SongLibraryRoot
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
index 8d8eeb3..bff02d9 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
@@ -1,4 +1,5 @@
 using System;
+using System.Globalization;
 using System.IO;
 using System.Linq;
 using UnityEngine;
@@ -29,6 +30,7 @@ public sealed class MainMenuController : MonoBehaviour
         private VisualElement learnOverlay;
         private VisualElement settingsOverlay;
         private VisualElement onboardingOverlay;
+        private VisualElement chartAudioImportOverlay;
         private Label eyebrow;
         private Label status;
         private Label learnHeading;
@@ -70,6 +72,16 @@ public sealed class MainMenuController : MonoBehaviour
         private Button songRefreshButton;
         private Button songFolderButton;
         private Button songBackButton;
+        private Button songImportAudioButton;
+        private Label chartAudioFileLabel;
+        private TextField chartAudioTitleField;
+        private TextField chartAudioArtistField;
+        private TextField chartAudioBpmField;
+        private TextField chartAudioBarsField;
+        private TextField chartAudioBeatsField;
+        private Label chartAudioErrorLabel;
+        private Button chartAudioStartButton;
+        private Button chartAudioCancelButton;
         private ScrollView learnList;
         private Label learnProgressCount;
         private Label learnProgressAccuracy;
@@ -150,6 +162,7 @@ public sealed class MainMenuController : MonoBehaviour
         private HtkSongInboxResult packageInbox;
         private string selectedSongId;
         private string selectedSongDifficulty;
+        private string pendingChartAudioPath;
         private double selectedSongSpeed = 1.0;
         private GameplayLessonId selectedLesson = GameplayLessonId.FirstPulse;
         private double selectedStudySpeed = 1.0;
@@ -187,6 +200,9 @@ public sealed class MainMenuController : MonoBehaviour
         public string SelectedSongId => selectedSongId;
         public SongLibrarySnapshot SongLibrary => songLibrary;
         public MainMenuStageEnvironment StageEnvironment => stageEnvironment;
+        public bool IsChartAudioImportVisible =>
+            chartAudioImportOverlay != null && chartAudioImportOverlay.resolvedStyle.display != DisplayStyle.None;
+        public string PendingChartAudioPath => pendingChartAudioPath;
 
         private void Awake()
         {
@@ -426,6 +442,17 @@ private void TryBind()
             songRefreshButton = Required<Button>(root, "song-refresh-button");
             songFolderButton = Required<Button>(root, "song-folder-button");
             songBackButton = Required<Button>(root, "song-back-button");
+            songImportAudioButton = Required<Button>(root, "song-import-audio-button");
+            chartAudioImportOverlay = Required<VisualElement>(root, "chart-audio-import-overlay");
+            chartAudioFileLabel = Required<Label>(root, "chart-audio-file");
+            chartAudioTitleField = Required<TextField>(root, "chart-audio-title");
+            chartAudioArtistField = Required<TextField>(root, "chart-audio-artist");
+            chartAudioBpmField = Required<TextField>(root, "chart-audio-bpm");
+            chartAudioBarsField = Required<TextField>(root, "chart-audio-bars");
+            chartAudioBeatsField = Required<TextField>(root, "chart-audio-beats");
+            chartAudioErrorLabel = Required<Label>(root, "chart-audio-error");
+            chartAudioStartButton = Required<Button>(root, "chart-audio-start");
+            chartAudioCancelButton = Required<Button>(root, "chart-audio-cancel");
             learnList = Required<ScrollView>(root, "learn-list");
             learnProgressCount = Required<Label>(root, "learn-progress-count");
             learnProgressAccuracy = Required<Label>(root, "learn-progress-accuracy");
@@ -523,6 +550,9 @@ private void TryBind()
             songRefreshButton.clicked += RefreshSongLibrary;
             songFolderButton.clicked += OpenUserSongFolder;
             songBackButton.clicked += CloseSongLibrary;
+            songImportAudioButton.clicked += PickChartAuthoringAudio;
+            chartAudioStartButton.clicked += ImportAudioAndStartChartCreatorFromButton;
+            chartAudioCancelButton.clicked += CancelChartAuthoringAudio;
             learnSpeedHalfButton.clicked += SelectHalfSpeed;
             learnSpeedThreeQuarterButton.clicked += SelectThreeQuarterSpeed;
             learnSpeedFullButton.clicked += SelectFullSpeed;
@@ -586,6 +616,7 @@ private void TryBind()
             RenderCopy();
             settingsVisible = false;
             SetOverlay(settingsOverlay, false);
+            SetOverlay(chartAudioImportOverlay, false);
             onboardingVisible = !PlayerPreferencesRuntime.Current.Snapshot.FirstRunCompleted;
             SetOverlay(onboardingOverlay, onboardingVisible);
             if (session.ReturnTarget == GameplayReturnTarget.LearningPath)
@@ -632,6 +663,9 @@ private void Unbind()
             songRefreshButton.clicked -= RefreshSongLibrary;
             songFolderButton.clicked -= OpenUserSongFolder;
             songBackButton.clicked -= CloseSongLibrary;
+            songImportAudioButton.clicked -= PickChartAuthoringAudio;
+            chartAudioStartButton.clicked -= ImportAudioAndStartChartCreatorFromButton;
+            chartAudioCancelButton.clicked -= CancelChartAuthoringAudio;
             learnSpeedHalfButton.clicked -= SelectHalfSpeed;
             learnSpeedThreeQuarterButton.clicked -= SelectThreeQuarterSpeed;
             learnSpeedFullButton.clicked -= SelectFullSpeed;
@@ -766,7 +800,7 @@ public bool StartSelectedSong()
         public bool StartChartCreator()
         {
             SongLibraryEntry song = SelectedSong();
-            if (song == null || !song.IsPlayable)
+            if (song == null || (!song.IsPlayable && !song.CanAuthorChart))
             {
                 RenderSongLibrary();
                 return false;
@@ -779,6 +813,93 @@ public bool StartChartCreator()
 
         private void StartChartCreatorFromButton() => StartChartCreator();
 
+        private void PickChartAuthoringAudio()
+        {
+            try
+            {
+                string path = new MacOsChartAuthoringAudioPicker().PickAudioFile();
+                if (!string.IsNullOrWhiteSpace(path)) BeginChartAuthoringAudio(path);
+            }
+            catch (Exception exception)
+            {
+                songLibraryDiagnostic.text = (Language == MainMenuLanguage.Italian
+                    ? "IMPORT AUDIO NON RIUSCITO · "
+                    : "AUDIO IMPORT FAILED · ") + exception.Message;
+            }
+        }
+
+        public void BeginChartAuthoringAudio(string sourceAudioPath)
+        {
+            string path = ChartAuthoringAudioImporter.ValidateSource(sourceAudioPath);
+            pendingChartAudioPath = path;
+            chartAudioFileLabel.text = Path.GetFileName(path);
+            chartAudioTitleField.value = Path.GetFileNameWithoutExtension(path).Replace('_', ' ').Replace('-', ' ');
+            chartAudioArtistField.value = string.Empty;
+            chartAudioBpmField.value = string.Empty;
+            chartAudioBarsField.value = string.Empty;
+            chartAudioBeatsField.value = string.Empty;
+            chartAudioErrorLabel.text = Language == MainMenuLanguage.Italian
+                ? "Inserisci dati verificati per questa precisa versione audio."
+                : "Enter values verified for this exact audio version.";
+            SetOverlay(chartAudioImportOverlay, true);
+            chartAudioTitleField.Focus();
+        }
+
+        public bool ImportAudioAndStartChartCreator(string libraryRoot = null)
+        {
+            try
+            {
+                if (string.IsNullOrWhiteSpace(pendingChartAudioPath))
+                    throw new InvalidOperationException("Select an audio file first.");
+                if (!TryParseDouble(chartAudioBpmField.value, out double bpm))
+                    throw new InvalidOperationException("BPM must be a positive number.");
+                if (!int.TryParse(chartAudioBarsField.value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int bars))
+                    throw new InvalidOperationException("Bars must be a positive whole number.");
+                if (!int.TryParse(chartAudioBeatsField.value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int beats))
+                    throw new InvalidOperationException("Beats per bar must be a positive whole number.");
+
+                var request = new ChartAuthoringAudioRequest(
+                    pendingChartAudioPath,
+                    chartAudioTitleField.value,
+                    chartAudioArtistField.value,
+                    bpm,
+                    bars,
+                    beats);
+                ChartAuthoringAudioImportResult imported = new ChartAuthoringAudioImporter().Import(
+                    request,
+                    string.IsNullOrWhiteSpace(libraryRoot) ? SongLibraryRuntime.UserRoot : libraryRoot,
+                    DateTimeOffset.UtcNow);
+
+                pendingChartAudioPath = null;
+                SetOverlay(chartAudioImportOverlay, false);
+                GameplaySessionContext.SelectChartCreator(imported.Song, 1.0, "easy");
+                Navigate(MainMenuRoutes.GameplayScene, MainMenuDestination.Play);
+                return IsNavigationPending;
+            }
+            catch (Exception exception)
+            {
+                chartAudioErrorLabel.text = (Language == MainMenuLanguage.Italian
+                    ? "CONTROLLA I DATI · "
+                    : "CHECK THE DETAILS · ") + exception.Message;
+                return false;
+            }
+        }
+
+        private void ImportAudioAndStartChartCreatorFromButton() => ImportAudioAndStartChartCreator();
+
+        private void CancelChartAuthoringAudio()
+        {
+            pendingChartAudioPath = null;
+            SetOverlay(chartAudioImportOverlay, false);
+        }
+
+        private static bool TryParseDouble(string value, out double result)
+        {
+            if (double.TryParse(value, NumberStyles.Float, CultureInfo.CurrentCulture, out result) && result > 0)
+                return true;
+            return double.TryParse(value, NumberStyles.Float, CultureInfo.InvariantCulture, out result) && result > 0;
+        }
+
         public void SelectSongSpeed(double speedMultiplier)
         {
             if (!GameplaySongSpeeds.IsSupported(speedMultiplier))
@@ -1220,6 +1341,7 @@ private void RenderSongLibrary()
             songLibrarySource.text = italian
                 ? "BUNDLED + CARTELLA UTENTE"
                 : "BUNDLED + USER FOLDER";
+            songImportAudioButton.text = italian ? "IMPORTA AUDIO E CREA" : "IMPORT AUDIO & CREATE";
 
             songList.Clear();
             for (int index = 0; index < songLibrary.Songs.Count; index++)
@@ -1291,14 +1413,19 @@ private void RenderSongLibrary()
             songEffectiveBpm.text = selected.Bpm.HasValue
                 ? $"{selected.Bpm.Value:0.#} BPM  →  {selected.Bpm.Value * selectedSongSpeed:0.#} BPM"
                 : "—";
-            songSpeedNote.text = selected.IsPlayable
-                ? (italian
-                    ? "Audio e chart rallentano insieme."
-                    : "Audio and chart slow down together.")
+            bool canRecordChart = selected.IsPlayable || selected.CanAuthorChart;
+            songSpeedNote.text = canRecordChart
+                ? selected.IsPlayable
+                    ? (italian
+                        ? "Audio e chart rallentano insieme."
+                        : "Audio and chart slow down together.")
+                    : (italian
+                        ? "L'audio rallenta mentre registri la prima chart."
+                        : "Audio slows down while you record the first chart.")
                 : (italian
                     ? "Disponibile quando audio e chart sono pronti."
                     : "Available when audio and chart are ready.");
-            SetSongSpeedControlsEnabled(selected.IsPlayable);
+            SetSongSpeedControlsEnabled(canRecordChart);
             RenderSongSpeedSelection();
             songDetailReadiness.EnableInClassList("song-detail-readiness--missing", !selected.IsPlayable);
             if (selected.IsPlayable)
@@ -1310,12 +1437,18 @@ private void RenderSongLibrary()
             }
             else
             {
-                songDetailReadiness.text = SongAvailabilityLabel(selected, italian);
+                songDetailReadiness.text = selected.CanAuthorChart
+                    ? (italian
+                        ? "✓ AUDIO PRONTO · CHART DA REGISTRARE"
+                        : "✓ AUDIO READY · CHART TO RECORD")
+                    : SongAvailabilityLabel(selected, italian);
                 songPlayButton.text = italian ? "CONTENUTI NON DISPONIBILI" : "CONTENT UNAVAILABLE";
             }
             songPlayButton.SetEnabled(selected.IsPlayable);
-            songRecordButton.SetEnabled(selected.IsPlayable);
-            songRecordButton.text = italian ? "REGISTRA CHART" : "RECORD CHART";
+            songRecordButton.SetEnabled(canRecordChart);
+            songRecordButton.text = selected.CanAuthorChart && !selected.IsPlayable
+                ? (italian ? "REGISTRA PRIMA CHART" : "RECORD FIRST CHART")
+                : (italian ? "REGISTRA CHART" : "RECORD CHART");
             songRefreshButton.text = italian ? "AGGIORNA LIBRERIA" : "REFRESH LIBRARY";
             songFolderButton.text = italian ? "APRI CARTELLA BRANI" : "OPEN SONG FOLDER";
             songBackButton.text = italian ? "INDIETRO" : "BACK";
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs
new file mode 100644
index 0000000..0959882
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs
@@ -0,0 +1,159 @@
+using System;
+using System.IO;
+using System.IO.Compression;
+using System.Linq;
+using HitTheKit.Core;
+using HitTheKit.Unity.Gameplay;
+using HitTheKit.Unity.Input;
+using NUnit.Framework;
+
+namespace HitTheKit.Unity.Tests
+{
+    public sealed class ChartAuthoringAudioTests
+    {
+        private string root;
+        private string library;
+
+        [SetUp]
+        public void SetUp()
+        {
+            root = Path.Combine(Path.GetTempPath(), "hitthekit-authoring-audio-" + Guid.NewGuid().ToString("N"));
+            library = Path.Combine(root, "library");
+            Directory.CreateDirectory(root);
+            Directory.CreateDirectory(library);
+        }
+
+        [TearDown]
+        public void TearDown()
+        {
+            if (Directory.Exists(root)) Directory.Delete(root, true);
+        }
+
+        [Test]
+        public void Audio_import_creates_an_atomic_local_authoring_source_without_inventing_a_chart()
+        {
+            string source = Path.Combine(root, "My Backing.wav");
+            WriteWave(source);
+            byte[] original = File.ReadAllBytes(source);
+            var request = new ChartAuthoringAudioRequest(source, "My Song", "Local Artist", 118, 96, 4);
+
+            ChartAuthoringAudioImportResult result = new ChartAuthoringAudioImporter().Import(
+                request,
+                library,
+                new DateTimeOffset(2026, 8, 19, 14, 0, 0, TimeSpan.Zero));
+
+            Assert.That(result.Song.Id, Is.EqualTo("local-artist-my-song-authoring-20260819-140000"));
+            Assert.That(result.Song.IsPlayable, Is.False);
+            Assert.That(result.Song.CanAuthorChart, Is.True);
+            Assert.That(result.Song.AudioAvailability, Is.EqualTo(SongAudioAvailability.Available));
+            Assert.That(result.Song.ChartAvailability, Is.EqualTo(SongChartAvailability.Unavailable));
+            Assert.That(result.Song.ChartPath, Is.Null);
+            Assert.That(File.Exists(result.Song.AudioPath), Is.True);
+            Assert.That(File.ReadAllBytes(source), Is.EqualTo(original), "Import must not mutate the selected source file.");
+            Assert.That(Directory.GetDirectories(library, ".hitthekit-audio-*"), Is.Empty);
+        }
+
+        [Test]
+        public void Audio_import_rejects_unsupported_or_falsely_named_content_without_publishing_a_folder()
+        {
+            string mp3 = Path.Combine(root, "source.mp3");
+            File.WriteAllBytes(mp3, new byte[] { 1, 2, 3 });
+            string fakeWave = Path.Combine(root, "fake.wav");
+            File.WriteAllBytes(fakeWave, new byte[] { 1, 2, 3, 4, 5 });
+
+            Assert.Throws<ChartAuthoringAudioImportException>(() =>
+                ChartAuthoringAudioImporter.ValidateSource(mp3));
+            Assert.Throws<ChartAuthoringAudioImportException>(() =>
+                new ChartAuthoringAudioImporter().Import(
+                    new ChartAuthoringAudioRequest(fakeWave, "Song", "Artist", 120, 8, 4),
+                    library,
+                    DateTimeOffset.UtcNow));
+            Assert.That(Directory.GetDirectories(library), Is.Empty);
+        }
+
+        [Test]
+        public void Audio_only_song_uses_the_shared_gameplay_session_with_an_empty_authoring_timeline()
+        {
+            SongLibraryEntry song = ImportSong();
+
+            GameplaySessionDefinition session = GameplaySessionFactory.ChartCreator(
+                song,
+                GameplayPresentationTheme.ArcadeNeon,
+                0.6,
+                "easy");
+
+            Assert.That(session.IsChartCreator, Is.True);
+            Assert.That(session.Chart, Is.EqualTo(GameplaySessionChart.AuthoringEmpty));
+            Assert.That(session.ChartFilePath, Is.Null);
+            Assert.That(session.AudioFilePath, Is.EqualTo(song.AudioPath));
+            Assert.That(session.SpeedMultiplier, Is.EqualTo(0.6));
+            Assert.That(session.Bpm, Is.EqualTo(song.Bpm.Value * 0.6));
+        }
+
+        [Test]
+        public void Recorded_take_keeps_audio_local_while_the_portable_package_remains_chart_only()
+        {
+            string source = Path.Combine(root, "source.wav");
+            WriteWave(source);
+            var recording = new ChartRecordingSession(8);
+            recording.Record(new DrumInputEvent(DrumPad.Kick, 100, 1, DrumInputSource.Test));
+            var metadata = new ChartCreatorMetadata("source-song", "Source Song", "Local Artist", "easy", 120, 4, 4);
+
+            ChartCreatorExportResult result = new ChartCreatorExporter().ExportChartOnly(
+                recording.Finish(),
+                metadata,
+                ChartQuantization.None,
+                library,
+                new DateTimeOffset(2026, 8, 19, 14, 30, 0, TimeSpan.Zero),
+                source);
+            SongLibraryEntry local = new SongLibraryDiscovery().Discover(new[]
+            {
+                new SongLibraryRoot(library, SongLibraryOrigin.UserFolder)
+            }).Songs.Single();
+
+            Assert.That(result.IsLocallyPlayable, Is.True);
+            Assert.That(File.Exists(result.LocalAudioPath), Is.True);
+            Assert.That(local.IsPlayable, Is.True);
+            using (var stream = File.OpenRead(result.PackagePath))
+            using (var archive = new ZipArchive(stream, ZipArchiveMode.Read))
+            using (var reader = new StreamReader(archive.GetEntry(HtkSongPackageService.ManifestEntryName).Open()))
+            {
+                string packageManifest = reader.ReadToEnd();
+                Assert.That(archive.Entries.Select(entry => entry.FullName), Is.EquivalentTo(new[]
+                {
+                    HtkSongPackageService.VersionEntryName,
+                    HtkSongPackageService.ManifestEntryName,
+                    HtkSongPackageService.ChartEntryName
+                }));
+                Assert.That(packageManifest, Does.Contain("\"audioAvailability\": \"missing\""));
+                Assert.That(packageManifest, Does.Not.Contain("audioFile"));
+            }
+        }
+
+        private SongLibraryEntry ImportSong()
+        {
+            string source = Path.Combine(root, "source.wav");
+            WriteWave(source);
+            return new ChartAuthoringAudioImporter().Import(
+                new ChartAuthoringAudioRequest(source, "Song", "Artist", 120, 8, 4),
+                library,
+                new DateTimeOffset(2026, 8, 19, 15, 0, 0, TimeSpan.Zero)).Song;
+        }
+
+        private static void WriteWave(string path)
+        {
+            // Minimal PCM WAVE with one silent mono sample. The production loader verifies
+            // the container signature; Unity decodes normal user WAV files at runtime.
+            byte[] wave =
+            {
+                0x52, 0x49, 0x46, 0x46, 0x26, 0x00, 0x00, 0x00,
+                0x57, 0x41, 0x56, 0x45, 0x66, 0x6d, 0x74, 0x20,
+                0x10, 0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00,
+                0x40, 0x1f, 0x00, 0x00, 0x80, 0x3e, 0x00, 0x00,
+                0x02, 0x00, 0x10, 0x00, 0x64, 0x61, 0x74, 0x61,
+                0x02, 0x00, 0x00, 0x00, 0x00, 0x00
+            };
+            File.WriteAllBytes(path, wave);
+        }
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs.meta
new file mode 100644
index 0000000..2211015
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartAuthoringAudioTests.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 045a2dffb90049a38fc42c0dcdf1f78a
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
index 0c45f2a..7c96058 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
@@ -204,6 +204,74 @@ public IEnumerator Chart_creator_launches_the_real_gameplay_session_for_the_sele
             LogAssert.NoUnexpectedReceived();
         }
 
+        [UnityTest]
+        public IEnumerator Chart_creator_audio_import_opens_a_guided_metadata_form_without_exposing_the_local_path()
+        {
+            string audio = Path.Combine(Application.temporaryCachePath, "authoring-ui.wav");
+            WriteSilentWave(audio);
+            MainMenuController controller = null;
+            yield return LoadMainMenu(value => controller = value);
+            controller.ShowSongLibrary();
+
+            controller.BeginChartAuthoringAudio(audio);
+            yield return null;
+
+            VisualElement root = controller.GetComponent<UIDocument>().rootVisualElement;
+            Assert.That(controller.IsChartAudioImportVisible, Is.True);
+            Assert.That(root.Q<VisualElement>("chart-audio-import-overlay").resolvedStyle.display,
+                Is.EqualTo(DisplayStyle.Flex));
+            Assert.That(root.Q<Label>("chart-audio-file").text, Is.EqualTo("authoring-ui.wav"));
+            Assert.That(root.Q<Label>("chart-audio-file").text, Does.Not.Contain(Application.temporaryCachePath));
+            Assert.That(root.Q<TextField>("chart-audio-title").value, Is.EqualTo("authoring ui"));
+            Assert.That(root.Q<TextField>("chart-audio-artist").value, Is.Empty);
+            Assert.That(root.Q<TextField>("chart-audio-bpm").value, Is.Empty,
+                "Unknown timing must not be silently replaced with a default BPM.");
+            Assert.That(root.Q<TextField>("chart-audio-bars").value, Is.Empty);
+            Assert.That(root.Q<TextField>("chart-audio-beats").value, Is.Empty);
+            Assert.That(root.Q<Button>("chart-audio-start"), Is.Not.Null);
+            Assert.That(root.Q<Button>("chart-audio-cancel"), Is.Not.Null);
+
+            File.Delete(audio);
+            LogAssert.NoUnexpectedReceived();
+        }
+
+        [UnityTest]
+        public IEnumerator Audio_only_authoring_source_loads_the_real_dsp_audio_with_an_empty_chart()
+        {
+            string root = Path.Combine(Application.temporaryCachePath, "hitthekit-authoring-session-" +
+                System.Guid.NewGuid().ToString("N"));
+            Directory.CreateDirectory(root);
+            string source = Path.Combine(root, "source.wav");
+            WriteSilentWave(source);
+            SongLibraryEntry song = new ChartAuthoringAudioImporter().Import(
+                new ChartAuthoringAudioRequest(source, "Authoring Song", "Local Artist", 120, 1, 4),
+                Path.Combine(root, "library"),
+                new System.DateTimeOffset(2026, 8, 19, 15, 0, 0, System.TimeSpan.Zero)).Song;
+            GameplaySessionContext.SelectChartCreator(song, 1.0, "easy");
+
+            AsyncOperation operation = SceneManager.LoadSceneAsync(MainMenuRoutes.GameplayScene, LoadSceneMode.Single);
+            while (!operation.isDone) yield return null;
+            var clock = Object.FindFirstObjectByType<HitTheKit.Unity.Audio.DspSongClockPrototype>();
+            float deadline = Time.realtimeSinceStartup + 4f;
+            while (clock.GeneratedClip == null && string.IsNullOrEmpty(clock.LoadError) &&
+                   Time.realtimeSinceStartup < deadline)
+                yield return null;
+
+            GameplayHighwayController gameplay = Object.FindFirstObjectByType<GameplayHighwayController>();
+            var timeline = Object.FindFirstObjectByType<HitTheKit.Unity.Charts.ChartTimelinePrototype>();
+            Assert.That(gameplay.CurrentSession.IsChartCreator, Is.True);
+            Assert.That(gameplay.CurrentSession.Chart, Is.EqualTo(GameplaySessionChart.AuthoringEmpty));
+            Assert.That(clock.ExternalAudioPath, Is.EqualTo(song.AudioPath));
+            Assert.That(clock.LoadError, Is.Null.Or.Empty);
+            Assert.That(clock.GeneratedClip, Is.Not.Null);
+            Assert.That(timeline.Chart.Notes, Is.Empty);
+            Assert.That(Object.FindFirstObjectByType<HitTheKit.Unity.Matching.HitMatchingPrototype>()
+                .Session.Notes, Is.Empty);
+
+            Directory.Delete(root, true);
+            LogAssert.NoUnexpectedReceived();
+        }
+
         [UnityTest]
         public IEnumerator Compact_song_library_keeps_rows_controls_and_actions_inside_their_panels()
         {
@@ -510,6 +578,30 @@ private static void AssertContained(VisualElement container, VisualElement child
             Assert.That(inner.yMax, Is.LessThanOrEqualTo(outer.yMax + PixelTolerance), description);
         }
 
+        private static void WriteSilentWave(string path)
+        {
+            const int sampleRate = 8000;
+            const int sampleCount = 8000;
+            using (var stream = new FileStream(path, FileMode.Create, FileAccess.Write, FileShare.None))
+            using (var writer = new BinaryWriter(stream))
+            {
+                writer.Write(new[] { (byte)'R', (byte)'I', (byte)'F', (byte)'F' });
+                writer.Write(36 + sampleCount * 2);
+                writer.Write(new[] { (byte)'W', (byte)'A', (byte)'V', (byte)'E' });
+                writer.Write(new[] { (byte)'f', (byte)'m', (byte)'t', (byte)' ' });
+                writer.Write(16);
+                writer.Write((short)1);
+                writer.Write((short)1);
+                writer.Write(sampleRate);
+                writer.Write(sampleRate * 2);
+                writer.Write((short)2);
+                writer.Write((short)16);
+                writer.Write(new[] { (byte)'d', (byte)'a', (byte)'t', (byte)'a' });
+                writer.Write(sampleCount * 2);
+                for (int index = 0; index < sampleCount; index++) writer.Write((short)0);
+            }
+        }
+
         private static IEnumerator LoadMainMenu(System.Action<MainMenuController> ready)
         {
             AsyncOperation operation = SceneManager.LoadSceneAsync(MainMenuRoutes.MainMenuScene, LoadSceneMode.Single);
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
index 8d6721f..820c724 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
@@ -1002,6 +1002,48 @@
     -unity-font-style: bold;
 }
 .song-library-secondary:hover, .song-library-secondary:focus { border-color: white; color: white; }
+.song-import-audio-button { border-color: rgb(230, 145, 48); color: rgb(255, 185, 91); }
+
+.chart-audio-import-layer { background-color: rgba(0, 2, 7, 0.9); }
+.chart-audio-import-panel {
+    width: 720px;
+    min-height: 610px;
+    padding: 28px 38px;
+    justify-content: flex-start;
+    border-color: rgb(230, 145, 48);
+    background-color: rgba(5, 10, 18, 0.99);
+}
+.chart-audio-import-title { margin-top: 7px; color: white; font-size: 31px; -unity-font-style: bold; }
+.chart-audio-file {
+    margin-top: 13px;
+    padding: 9px 12px;
+    color: rgb(73, 216, 255);
+    font-size: 13px;
+    -unity-font-style: bold;
+    background-color: rgba(9, 34, 47, 0.9);
+    border-width: 1px;
+    border-color: rgba(73, 216, 255, 0.5);
+    border-radius: 5px;
+}
+.chart-audio-import-copy { margin-top: 12px; color: rgb(173, 193, 208); font-size: 12px; white-space: normal; }
+.chart-audio-fields { margin-top: 15px; }
+.chart-audio-field-row { flex-direction: row; justify-content: space-between; }
+.chart-audio-field { width: 31.5%; margin-top: 10px; }
+.chart-audio-field--wide { width: 100%; }
+.chart-audio-field-label { margin-bottom: 5px; color: rgb(120, 192, 220); font-size: 9px; -unity-font-style: bold; letter-spacing: 1px; }
+.chart-audio-text-field { height: 38px; color: white; background-color: rgb(9, 19, 29); }
+.chart-audio-text-field .unity-text-input {
+    padding-left: 10px;
+    color: white;
+    background-color: rgb(9, 19, 29);
+    border-width: 1px;
+    border-color: rgb(52, 86, 108);
+    border-radius: 4px;
+}
+.chart-audio-text-field:focus .unity-text-input { border-color: rgb(73, 216, 255); }
+.chart-audio-error { min-height: 34px; margin-top: 12px; color: rgb(255, 178, 70); font-size: 11px; white-space: normal; }
+.chart-audio-actions { flex-direction: row; justify-content: flex-end; }
+.chart-audio-actions .modal-secondary, .chart-audio-actions .modal-primary { min-width: 190px; }
 
 .main-menu--compact .song-library-section { left: 6px; top: 8px; right: 6px; }
 .main-menu--compact .song-library-rail { width: 104px; min-width: 104px; }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
index 01e1a48..03677d5 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
@@ -125,6 +125,7 @@
                 <ui:VisualElement class="song-library-footer">
                     <ui:Label name="song-library-diagnostic" class="song-library-diagnostic" />
                     <ui:VisualElement class="song-library-actions">
+                        <ui:Button name="song-import-audio-button" text="IMPORTA AUDIO E CREA" class="song-library-secondary song-import-audio-button" />
                         <ui:Button name="song-refresh-button" text="AGGIORNA LIBRERIA" class="song-library-secondary" />
                         <ui:Button name="song-folder-button" text="APRI CARTELLA BRANI" class="song-library-secondary" />
                         <ui:Button name="song-back-button" text="INDIETRO" class="song-library-secondary" />
@@ -133,6 +134,44 @@
             </ui:VisualElement>
         </ui:VisualElement>
 
+        <ui:VisualElement name="chart-audio-import-overlay" class="modal-layer chart-audio-import-layer" style="display: none;">
+            <ui:VisualElement class="modal-panel chart-audio-import-panel">
+                <ui:Label text="CHART CREATOR · NUOVO BRANO" class="modal-eyebrow" />
+                <ui:Label text="IMPORTA LA BASE AUDIO" class="chart-audio-import-title" />
+                <ui:Label name="chart-audio-file" class="chart-audio-file" />
+                <ui:Label text="L'audio viene copiato soltanto nella tua libreria locale. Il pacchetto .htksong conterrà esclusivamente la chart." class="chart-audio-import-copy" />
+                <ui:VisualElement class="chart-audio-fields">
+                    <ui:VisualElement class="chart-audio-field chart-audio-field--wide">
+                        <ui:Label text="TITOLO" class="chart-audio-field-label" />
+                        <ui:TextField name="chart-audio-title" class="chart-audio-text-field" />
+                    </ui:VisualElement>
+                    <ui:VisualElement class="chart-audio-field chart-audio-field--wide">
+                        <ui:Label text="ARTISTA / AUTORE" class="chart-audio-field-label" />
+                        <ui:TextField name="chart-audio-artist" class="chart-audio-text-field" />
+                    </ui:VisualElement>
+                    <ui:VisualElement class="chart-audio-field-row">
+                        <ui:VisualElement class="chart-audio-field">
+                            <ui:Label text="BPM VERIFICATI" class="chart-audio-field-label" />
+                            <ui:TextField name="chart-audio-bpm" class="chart-audio-text-field" />
+                        </ui:VisualElement>
+                        <ui:VisualElement class="chart-audio-field">
+                            <ui:Label text="BATTUTE" class="chart-audio-field-label" />
+                            <ui:TextField name="chart-audio-bars" class="chart-audio-text-field" />
+                        </ui:VisualElement>
+                        <ui:VisualElement class="chart-audio-field">
+                            <ui:Label text="BEAT PER BATTUTA" class="chart-audio-field-label" />
+                            <ui:TextField name="chart-audio-beats" class="chart-audio-text-field" />
+                        </ui:VisualElement>
+                    </ui:VisualElement>
+                </ui:VisualElement>
+                <ui:Label name="chart-audio-error" class="chart-audio-error" />
+                <ui:VisualElement class="modal-actions chart-audio-actions">
+                    <ui:Button name="chart-audio-cancel" text="ANNULLA" class="modal-secondary" />
+                    <ui:Button name="chart-audio-start" text="IMPORTA E REGISTRA" class="modal-primary" />
+                </ui:VisualElement>
+            </ui:VisualElement>
+        </ui:VisualElement>
+
         <ui:VisualElement name="learn-overlay" class="learn-section">
             <ui:VisualElement class="learn-rail">
                 <ui:VisualElement class="learn-brand">

From ddd8991fa7ce66fc622fea2f1ae03cb9f5891c9e Mon Sep 17 00:00:00 2001
From: Baron Luca <baron_luca@hotmail.it>
Date: Wed, 19 Aug 2026 15:24:13 +0200
Subject: [PATCH 4/5] feat(charts): add note editing and local audio binding

---
 docs/development/chart-creator.md             |  21 +-
 docs/development/song-library.md              |  12 +-
 .../Runtime/Gameplay/ChartDraftEditor.cs      | 120 +++++++++++
 .../Runtime/Gameplay/ChartDraftEditor.cs.meta |  11 +
 .../Gameplay/GameplayHighwayController.cs     | 191 +++++++++++++++++-
 .../Runtime/Gameplay/SongAudioBinding.cs      | 171 ++++++++++++++++
 .../Runtime/Gameplay/SongAudioBinding.cs.meta |  11 +
 .../HitTheKit/Runtime/Gameplay/SongLibrary.cs |   6 +
 .../Runtime/MainMenu/MainMenuController.cs    | 103 ++++++++++
 .../Tests/EditMode/ChartCreatorTests.cs       |  47 +++++
 .../Tests/EditMode/HtkSongPackageTests.cs     |  73 +++++++
 .../Tests/PlayMode/MainMenuPlayModeTests.cs   |   9 +
 .../HitTheKit/UI/Gameplay/GameplayHighway.uss |  14 ++
 .../UI/Gameplay/GameplayHighway.uxml          |  38 +++-
 .../Assets/HitTheKit/UI/MainMenu/MainMenu.uss |   3 +
 .../HitTheKit/UI/MainMenu/MainMenu.uxml       |  16 ++
 16 files changed, 824 insertions(+), 22 deletions(-)
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs.meta
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs.meta

diff --git a/docs/development/chart-creator.md b/docs/development/chart-creator.md
index 8503785..6e2038b 100644
--- a/docs/development/chart-creator.md
+++ b/docs/development/chart-creator.md
@@ -17,8 +17,11 @@ timeline.
    current chart only as a playback reference.
 4. Play during the normal count-in and backing track. Hits before song time zero
    or beyond the declared song duration are ignored.
-5. At the result screen, review the captured-hit count and save the raw timing,
-   or quantize non-destructively to an eighth- or sixteenth-note grid.
+5. At the result screen, review the captured notes in the visual editor. Select
+   a note to change its time or drum pad, add missing notes, or delete unwanted
+   notes. The original recorded take remains unchanged in memory.
+6. Save the edited timing as recorded, or quantize the edited draft
+   non-destructively to an eighth- or sixteenth-note grid.
 
 Keyboard and MIDI events reach the recorder through `HitMatchingPrototype`'s
 `InputProcessed` boundary. Consequently, the existing per-source timing offset
@@ -44,7 +47,10 @@ entries:
 To transfer a take, copy only the `.htksong` file into
 `Documents/HTKSongs` on the other computer and refresh the Song Library. The
 game validates and atomically imports it. Existing song folders are never
-overwritten.
+overwritten. Select the imported entry, choose **Bind local audio**, select
+your own authorized WAV/OGG copy, and confirm the local-only binding. The game
+copies that audio into the imported song folder and makes the entry playable;
+the source file and portable package are not modified.
 
 The publish is atomic and both documents are parsed by the production loaders
 before the folder or package becomes visible. When the recording used a local
@@ -65,13 +71,14 @@ not a claim of authoritative transcription.
 
 ## Current foundation limits
 
-- Editing individual notes is not yet available. Raw/1/8/1/16 save choices are
-  the initial review tools.
+- The visual editor supports individual note time/pad changes, additions and
+  deletions. Waveform scrubbing and articulation/velocity authoring are future
+  editing tools.
 - The schema currently stores pad and time. Velocity and articulation remain in
   the in-memory take but schema v1 does not serialize them.
 - The native picker currently targets macOS. WAV and OGG are supported; MP3 is
   intentionally rejected by the production loader.
 - The author must enter BPM, bars and meter explicitly. Unknown timing never
   receives a hidden default.
-- Portable packages remain chart-only; imported packages require an authorized
-  local audio binding on the receiving computer.
+- Portable packages remain chart-only; the receiving computer must explicitly
+  bind an authorized local WAV/OGG copy before the imported chart is playable.
diff --git a/docs/development/song-library.md b/docs/development/song-library.md
index 9e5c304..81cbfa1 100644
--- a/docs/development/song-library.md
+++ b/docs/development/song-library.md
@@ -121,6 +121,12 @@ copied to another computer; subsequent refreshes are idempotent.
 Package schema version 1 contains no audio and rejects any audio declaration or
 extra archive entry. Imports are bounded to 5 MiB, reject links, duplicate or
 case-colliding names, malformed ZIP/JSON/chart data, unsupported versions and
-path traversal, and never replace an existing song folder. An imported chart is
-therefore visible but unavailable until the player explicitly supplies audio
-they are entitled to use through the ordinary local song binding.
+path traversal, and never replace an existing song folder.
+
+An imported chart is therefore visible but unavailable until the player
+selects **Bind local audio** and supplies a WAV/OGG file they are entitled to
+use. The confirmation panel identifies the selected song and local filename;
+on confirmation the game copies the audio into that song's direct user-library
+folder, atomically updates its manifest, and refreshes the entry as playable.
+The source audio and `.htksong` package are never modified, and no absolute
+machine path is persisted.
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs
new file mode 100644
index 0000000..80954a2
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs
@@ -0,0 +1,120 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using HitTheKit.Core;
+using HitTheKit.Unity.Input;
+
+namespace HitTheKit.Unity.Gameplay
+{
+    public sealed class EditableChartNote
+    {
+        internal EditableChartNote(
+            int identity,
+            DrumPad pad,
+            int velocity,
+            double timeSeconds,
+            DrumInputSource source)
+        {
+            Identity = identity;
+            Pad = pad;
+            Velocity = velocity;
+            TimeSeconds = timeSeconds;
+            Source = source;
+        }
+
+        public int Identity { get; }
+        public DrumPad Pad { get; internal set; }
+        public int Velocity { get; }
+        public double TimeSeconds { get; internal set; }
+        public DrumInputSource Source { get; }
+    }
+
+    public sealed class ChartDraftEditor
+    {
+        private readonly double durationSeconds;
+        private readonly List<EditableChartNote> notes;
+        private readonly ReadOnlyCollection<EditableChartNote> readOnlyNotes;
+        private int nextIdentity;
+
+        public ChartDraftEditor(ChartRecordingDraft draft)
+        {
+            if (draft == null) throw new ArgumentNullException(nameof(draft));
+            durationSeconds = draft.DurationSeconds;
+            notes = new List<EditableChartNote>(draft.Hits.Count);
+            for (int index = 0; index < draft.Hits.Count; index++)
+            {
+                RecordedChartHit hit = draft.Hits[index];
+                notes.Add(new EditableChartNote(nextIdentity++, hit.Pad, hit.Velocity, hit.TimeSeconds, hit.Source));
+            }
+            Sort();
+            readOnlyNotes = notes.AsReadOnly();
+        }
+
+        public double DurationSeconds => durationSeconds;
+        public IReadOnlyList<EditableChartNote> Notes => readOnlyNotes;
+
+        public int Update(int index, double timeSeconds, DrumPad pad)
+        {
+            EditableChartNote note = At(index);
+            ValidateTime(timeSeconds);
+            ValidatePad(pad);
+            note.TimeSeconds = timeSeconds;
+            note.Pad = pad;
+            Sort();
+            return notes.IndexOf(note);
+        }
+
+        public int Add(double timeSeconds, DrumPad pad, int velocity = 100)
+        {
+            ValidateTime(timeSeconds);
+            ValidatePad(pad);
+            if (velocity < 0 || velocity > 127) throw new ArgumentOutOfRangeException(nameof(velocity));
+            if (notes.Count >= ChartRecordingSession.MaximumHits)
+                throw new InvalidOperationException($"A chart cannot exceed {ChartRecordingSession.MaximumHits} notes.");
+            var note = new EditableChartNote(nextIdentity++, pad, velocity, timeSeconds, DrumInputSource.Test);
+            notes.Add(note);
+            Sort();
+            return notes.IndexOf(note);
+        }
+
+        public void Delete(int index) => notes.RemoveAt(ValidatedIndex(index));
+
+        public ChartRecordingDraft BuildDraft()
+        {
+            var hits = new RecordedChartHit[notes.Count];
+            for (int index = 0; index < notes.Count; index++)
+            {
+                EditableChartNote note = notes[index];
+                hits[index] = new RecordedChartHit(
+                    new DrumInputEvent(note.Pad, note.Velocity, note.TimeSeconds, note.Source),
+                    index);
+            }
+            return new ChartRecordingDraft(durationSeconds, hits);
+        }
+
+        private EditableChartNote At(int index) => notes[ValidatedIndex(index)];
+
+        private int ValidatedIndex(int index)
+        {
+            if (index < 0 || index >= notes.Count) throw new ArgumentOutOfRangeException(nameof(index));
+            return index;
+        }
+
+        private void ValidateTime(double value)
+        {
+            if (double.IsNaN(value) || double.IsInfinity(value) || value < 0 || value > durationSeconds)
+                throw new ArgumentOutOfRangeException(nameof(value), $"Note time must be between 0 and {durationSeconds:0.###} seconds.");
+        }
+
+        private static void ValidatePad(DrumPad pad)
+        {
+            if (!Enum.IsDefined(typeof(DrumPad), pad)) throw new ArgumentOutOfRangeException(nameof(pad));
+        }
+
+        private void Sort() => notes.Sort((left, right) =>
+        {
+            int byTime = left.TimeSeconds.CompareTo(right.TimeSeconds);
+            return byTime != 0 ? byTime : left.Identity.CompareTo(right.Identity);
+        });
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs.meta
new file mode 100644
index 0000000..66036f9
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: a1f6bc7d8a244151b6712fdd0bf0fc77
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
index e52762f..92c69c2 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
@@ -1,4 +1,5 @@
 using System;
+using System.Collections;
 using System.Collections.Generic;
 using System.Globalization;
 using System.IO;
@@ -76,12 +77,21 @@ public sealed class GameplayHighwayController : MonoBehaviour
         private Label resultBreakdownLabel;
         private Label resultPracticeLabel;
         private Label resultCalibrationLabel;
+        private VisualElement resultPerformancePanel;
         private VisualElement chartCreatorResults;
         private Label chartCreatorSummaryLabel;
         private Label chartCreatorStatusLabel;
         private Button chartSaveRawButton;
         private Button chartSaveEighthButton;
         private Button chartSaveSixteenthButton;
+        private ListView chartNoteList;
+        private Label chartNoteSelectionLabel;
+        private TextField chartNoteTimeField;
+        private DropdownField chartNotePadField;
+        private Button chartNoteAddButton;
+        private Button chartNoteApplyButton;
+        private Button chartNoteDeleteButton;
+        private Label chartNoteStatusLabel;
         private GameplayHighwaySurface surface;
         private GameplayKitSurface kitSurface;
         private bool showInstructionalKit;
@@ -102,6 +112,7 @@ public sealed class GameplayHighwayController : MonoBehaviour
         private bool resultRecorded;
         private ChartRecordingSession chartRecording;
         private ChartRecordingDraft chartDraft;
+        private ChartDraftEditor chartDraftEditor;
 
         public event Action<GameplayPresentationTheme> ThemeChanged;
 
@@ -126,6 +137,7 @@ public sealed class GameplayHighwayController : MonoBehaviour
         public int RecordedChartHitCount => chartRecording?.HitCount ?? chartDraft?.Hits.Count ?? 0;
         public string LastChartExportPath { get; private set; }
         public string LastChartPackagePath { get; private set; }
+        public int EditableChartNoteCount => chartDraftEditor?.Notes.Count ?? 0;
 
         private void Awake()
         {
@@ -277,12 +289,22 @@ private void BindView()
             resultBreakdownLabel = root.Q<Label>("result-breakdown");
             resultPracticeLabel = root.Q<Label>("result-practice");
             resultCalibrationLabel = root.Q<Label>("result-calibration");
+            resultPerformancePanel = root.Q<VisualElement>("result-performance-panel");
             chartCreatorResults = root.Q<VisualElement>("chart-creator-results");
             chartCreatorSummaryLabel = root.Q<Label>("chart-creator-summary");
             chartCreatorStatusLabel = root.Q<Label>("chart-creator-status");
             chartSaveRawButton = root.Q<Button>("chart-save-raw");
             chartSaveEighthButton = root.Q<Button>("chart-save-eighth");
             chartSaveSixteenthButton = root.Q<Button>("chart-save-sixteenth");
+            chartNoteList = root.Q<ListView>("chart-note-list");
+            chartNoteSelectionLabel = root.Q<Label>("chart-note-selection");
+            chartNoteTimeField = root.Q<TextField>("chart-note-time");
+            chartNotePadField = root.Q<DropdownField>("chart-note-pad");
+            chartNoteAddButton = root.Q<Button>("chart-note-add");
+            chartNoteApplyButton = root.Q<Button>("chart-note-apply");
+            chartNoteDeleteButton = root.Q<Button>("chart-note-delete");
+            chartNoteStatusLabel = root.Q<Label>("chart-note-status");
+            ConfigureChartNoteEditorView();
             PlayerPreferencesSnapshot preferences = PlayerPreferencesRuntime.Current.Snapshot;
             root.EnableInClassList("gameplay--high-contrast", preferences.HighContrast);
             root.EnableInClassList("gameplay--reduced-motion", preferences.ReducedMotion);
@@ -516,6 +538,8 @@ public void RestartRun()
             practiceTimer.ResetAttempt();
             resultRecorded = false;
             chartDraft = null;
+            chartDraftEditor = null;
+            if (chartNoteList != null) chartNoteList.itemsSource = null;
             LastChartExportPath = null;
             LastChartPackagePath = null;
             chartRecording?.Restart();
@@ -565,6 +589,7 @@ private void ShowResults(HitMatchingSnapshot matchingSnapshot)
             if (CurrentSession.IsChartCreator)
             {
                 chartDraft = chartRecording?.Finish();
+                chartDraftEditor = chartDraft == null ? null : new ChartDraftEditor(chartDraft);
             }
             else
             {
@@ -573,7 +598,8 @@ private void ShowResults(HitMatchingSnapshot matchingSnapshot)
             resultRecorded = true;
             if (CurrentSession.IsChartCreator)
             {
-                int hitCount = chartDraft?.Hits.Count ?? 0;
+                int hitCount = chartDraftEditor?.Notes.Count ?? 0;
+                SetDisplayed(resultPerformancePanel, false);
                 resultRankLabel.text = "REC";
                 resultScoreLabel.text = hitCount.ToString("N0", CultureInfo.InvariantCulture);
                 resultAccuracyLabel.text = "TAKE";
@@ -588,10 +614,12 @@ private void ShowResults(HitMatchingSnapshot matchingSnapshot)
                 chartSaveRawButton?.SetEnabled(hitCount > 0);
                 chartSaveEighthButton?.SetEnabled(hitCount > 0);
                 chartSaveSixteenthButton?.SetEnabled(hitCount > 0);
+                RefreshChartNoteEditor(hitCount > 0 ? 0 : -1);
                 SetDisplayed(chartCreatorResults, true);
             }
             else
             {
+                SetDisplayed(resultPerformancePanel, true);
                 resultRankLabel.text = score.Rank;
                 resultScoreLabel.text = score.Score.ToString("N0", CultureInfo.InvariantCulture);
                 resultAccuracyLabel.text = $"{score.Accuracy:0.0}%";
@@ -622,12 +650,14 @@ private void InitializeChartCreator()
             {
                 chartRecording = null;
                 chartDraft = null;
+                chartDraftEditor = null;
                 return;
             }
 
             double playbackDuration = CurrentSession.Bars * CurrentSession.BeatsPerBar * 60.0 / CurrentSession.Bpm;
             chartRecording = new ChartRecordingSession(playbackDuration, CurrentSession.SpeedMultiplier);
             chartDraft = null;
+            chartDraftEditor = null;
         }
 
         public ChartCreatorExportResult SaveChartRecording(ChartQuantization quantization)
@@ -646,8 +676,9 @@ public ChartCreatorExportResult SaveChartRecording(ChartQuantization quantizatio
                 originalBpm,
                 CurrentSession.Bars,
                 CurrentSession.BeatsPerBar);
+            ChartRecordingDraft editedDraft = chartDraftEditor?.BuildDraft() ?? chartDraft;
             ChartCreatorExportResult result = new ChartCreatorExporter().ExportChartOnly(
-                chartDraft,
+                editedDraft,
                 metadata,
                 quantization,
                 SongLibraryRuntime.UserRoot,
@@ -667,6 +698,29 @@ public ChartCreatorExportResult SaveChartRecording(ChartQuantization quantizatio
         private void SaveEighthChart() => TrySaveChart(ChartQuantization.EighthNote);
         private void SaveSixteenthChart() => TrySaveChart(ChartQuantization.SixteenthNote);
 
+        public int EditChartNote(int index, double timeSeconds, DrumPad pad)
+        {
+            if (chartDraftEditor == null) throw new InvalidOperationException("Finish a Chart Creator take first.");
+            int selected = chartDraftEditor.Update(index, timeSeconds, pad);
+            RefreshChartNoteEditor(selected);
+            return selected;
+        }
+
+        public int AddChartNote(double timeSeconds, DrumPad pad)
+        {
+            if (chartDraftEditor == null) throw new InvalidOperationException("Finish a Chart Creator take first.");
+            int selected = chartDraftEditor.Add(timeSeconds, pad);
+            RefreshChartNoteEditor(selected);
+            return selected;
+        }
+
+        public void DeleteChartNote(int index)
+        {
+            if (chartDraftEditor == null) throw new InvalidOperationException("Finish a Chart Creator take first.");
+            chartDraftEditor.Delete(index);
+            RefreshChartNoteEditor(Math.Min(index, chartDraftEditor.Notes.Count - 1));
+        }
+
         private void TrySaveChart(ChartQuantization quantization)
         {
             try
@@ -775,6 +829,9 @@ private void BindRunControls()
             if (chartSaveRawButton != null) chartSaveRawButton.clicked += SaveRawChart;
             if (chartSaveEighthButton != null) chartSaveEighthButton.clicked += SaveEighthChart;
             if (chartSaveSixteenthButton != null) chartSaveSixteenthButton.clicked += SaveSixteenthChart;
+            if (chartNoteAddButton != null) chartNoteAddButton.clicked += AddChartNoteFromView;
+            if (chartNoteApplyButton != null) chartNoteApplyButton.clicked += ApplyChartNoteFromView;
+            if (chartNoteDeleteButton != null) chartNoteDeleteButton.clicked += DeleteChartNoteFromView;
         }
 
         private void UnbindRunControls()
@@ -788,6 +845,136 @@ private void UnbindRunControls()
             if (chartSaveRawButton != null) chartSaveRawButton.clicked -= SaveRawChart;
             if (chartSaveEighthButton != null) chartSaveEighthButton.clicked -= SaveEighthChart;
             if (chartSaveSixteenthButton != null) chartSaveSixteenthButton.clicked -= SaveSixteenthChart;
+            if (chartNoteAddButton != null) chartNoteAddButton.clicked -= AddChartNoteFromView;
+            if (chartNoteApplyButton != null) chartNoteApplyButton.clicked -= ApplyChartNoteFromView;
+            if (chartNoteDeleteButton != null) chartNoteDeleteButton.clicked -= DeleteChartNoteFromView;
+        }
+
+        private void ConfigureChartNoteEditorView()
+        {
+            if (chartNoteList == null || chartNotePadField == null) return;
+            chartNotePadField.choices = new List<string>();
+            foreach (DrumPad pad in Enum.GetValues(typeof(DrumPad)))
+                chartNotePadField.choices.Add(GameplayHighwayLanes.Find(pad).Label);
+            chartNotePadField.index = 0;
+            chartNoteList.fixedItemHeight = 30;
+            chartNoteList.virtualizationMethod = CollectionVirtualizationMethod.FixedHeight;
+            chartNoteList.selectionType = SelectionType.Single;
+            chartNoteList.makeItem = () =>
+            {
+                var label = new Label();
+                label.AddToClassList("chart-note-row");
+                return label;
+            };
+            chartNoteList.bindItem = (element, index) =>
+            {
+                var label = (Label)element;
+                if (chartDraftEditor == null || index < 0 || index >= chartDraftEditor.Notes.Count)
+                {
+                    label.text = string.Empty;
+                    return;
+                }
+                EditableChartNote note = chartDraftEditor.Notes[index];
+                label.text = $"{index + 1:000}   {note.TimeSeconds:0.000}s   {GameplayHighwayLanes.Find(note.Pad).Label}";
+            };
+            chartNoteList.selectionChanged -= HandleChartNoteSelectionChanged;
+            chartNoteList.selectionChanged += HandleChartNoteSelectionChanged;
+        }
+
+        private void HandleChartNoteSelectionChanged(IEnumerable<object> _) => RenderSelectedChartNote();
+
+        private void RefreshChartNoteEditor(int selectedIndex)
+        {
+            if (chartNoteList == null) return;
+            chartNoteList.itemsSource = chartDraftEditor?.Notes as IList;
+            chartNoteList.RefreshItems();
+            int count = chartDraftEditor?.Notes.Count ?? 0;
+            bool hasNotes = count > 0;
+            chartSaveRawButton?.SetEnabled(hasNotes);
+            chartSaveEighthButton?.SetEnabled(hasNotes);
+            chartSaveSixteenthButton?.SetEnabled(hasNotes);
+            chartNoteApplyButton?.SetEnabled(hasNotes);
+            chartNoteDeleteButton?.SetEnabled(hasNotes);
+            if (chartCreatorSummaryLabel != null)
+                chartCreatorSummaryLabel.text = $"{count} NOTE · {CurrentSession.Difficulty.ToUpperInvariant()}";
+            if (selectedIndex >= 0 && selectedIndex < count)
+            {
+                chartNoteList.SetSelection(selectedIndex);
+                chartNoteList.ScrollToItem(selectedIndex);
+            }
+            else
+            {
+                chartNoteList.ClearSelection();
+                RenderSelectedChartNote();
+            }
+        }
+
+        private void RenderSelectedChartNote()
+        {
+            int index = chartNoteList?.selectedIndex ?? -1;
+            if (chartDraftEditor == null || index < 0 || index >= chartDraftEditor.Notes.Count)
+            {
+                if (chartNoteSelectionLabel != null) chartNoteSelectionLabel.text = "SELEZIONA UNA NOTA";
+                if (chartNoteTimeField != null) chartNoteTimeField.value = string.Empty;
+                return;
+            }
+            EditableChartNote note = chartDraftEditor.Notes[index];
+            chartNoteSelectionLabel.text = $"NOTA {index + 1:000} · VELOCITY {note.Velocity}";
+            chartNoteTimeField.value = note.TimeSeconds.ToString("0.000", CultureInfo.InvariantCulture);
+            chartNotePadField.index = (int)note.Pad;
+        }
+
+        private void ApplyChartNoteFromView()
+        {
+            try
+            {
+                int index = chartNoteList?.selectedIndex ?? -1;
+                int selected = EditChartNote(index, ParseChartNoteTime(), SelectedChartNotePad());
+                chartNoteStatusLabel.text = $"NOTA {selected + 1:000} AGGIORNATA";
+            }
+            catch (Exception exception) { SetChartNoteError(exception); }
+        }
+
+        private void AddChartNoteFromView()
+        {
+            try
+            {
+                int selected = AddChartNote(ParseChartNoteTime(), SelectedChartNotePad());
+                chartNoteStatusLabel.text = $"NOTA {selected + 1:000} AGGIUNTA";
+            }
+            catch (Exception exception) { SetChartNoteError(exception); }
+        }
+
+        private void DeleteChartNoteFromView()
+        {
+            try
+            {
+                int index = chartNoteList?.selectedIndex ?? -1;
+                DeleteChartNote(index);
+                chartNoteStatusLabel.text = "NOTA ELIMINATA";
+            }
+            catch (Exception exception) { SetChartNoteError(exception); }
+        }
+
+        private double ParseChartNoteTime()
+        {
+            string value = chartNoteTimeField?.value;
+            if (double.TryParse(value, NumberStyles.Float, CultureInfo.CurrentCulture, out double current)) return current;
+            if (double.TryParse(value, NumberStyles.Float, CultureInfo.InvariantCulture, out double invariant)) return invariant;
+            throw new InvalidOperationException("Inserisci un tempo valido in secondi.");
+        }
+
+        private DrumPad SelectedChartNotePad()
+        {
+            int index = chartNotePadField?.index ?? -1;
+            if (index < 0 || index >= Enum.GetValues(typeof(DrumPad)).Length)
+                throw new InvalidOperationException("Seleziona uno strumento valido.");
+            return (DrumPad)index;
+        }
+
+        private void SetChartNoteError(Exception exception)
+        {
+            if (chartNoteStatusLabel != null) chartNoteStatusLabel.text = "MODIFICA NON RIUSCITA · " + exception.Message;
         }
 
         private TimingCalibrationAdvisor AdvisorFor(DrumInputSource source) =>
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs
new file mode 100644
index 0000000..6c85c2f
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs
@@ -0,0 +1,171 @@
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Text;
+
+namespace HitTheKit.Unity.Gameplay
+{
+    public sealed class SongAudioBindingException : Exception
+    {
+        public SongAudioBindingException(string message) : base(message) { }
+        public SongAudioBindingException(string message, Exception innerException) : base(message, innerException) { }
+    }
+
+    public sealed class SongAudioBindingResult
+    {
+        internal SongAudioBindingResult(SongLibraryEntry song, string sourcePath)
+        {
+            Song = song;
+            SourcePath = sourcePath;
+        }
+
+        public SongLibraryEntry Song { get; }
+        public string SourcePath { get; }
+    }
+
+    public sealed class SongAudioBindingService
+    {
+        private static readonly UTF8Encoding Utf8WithoutBom = new UTF8Encoding(false);
+
+        public SongAudioBindingResult Bind(
+            SongLibraryEntry song,
+            string sourceAudioPath,
+            string libraryRoot)
+        {
+            if (song == null) throw new ArgumentNullException(nameof(song));
+            if (!song.CanBindAudio)
+                throw new SongAudioBindingException("The selected song is not an imported chart awaiting local audio.");
+            if (string.IsNullOrWhiteSpace(libraryRoot))
+                throw new ArgumentException("Song-library root is required.", nameof(libraryRoot));
+
+            string source = ChartAuthoringAudioImporter.ValidateSource(sourceAudioPath);
+            string root = Path.GetFullPath(libraryRoot);
+            string folder = Path.GetFullPath(song.FolderPath);
+            ValidateSongBoundary(song, root, folder);
+
+            string manifestPath = Path.Combine(folder, SongLibraryDiscovery.ManifestFileName);
+            if (!File.Exists(manifestPath) || IsLink(manifestPath))
+                throw new SongAudioBindingException("The imported song manifest is missing or linked.");
+            if (!File.Exists(song.ChartPath) || IsLink(song.ChartPath))
+                throw new SongAudioBindingException("The imported chart is missing or linked.");
+
+            string extension = Path.GetExtension(source).ToLowerInvariant();
+            string audioName = "source-audio" + extension;
+            string destinationAudio = Path.Combine(folder, audioName);
+            if (File.Exists(destinationAudio))
+                throw new SongAudioBindingException("This song folder already contains a local audio binding.");
+
+            string token = Guid.NewGuid().ToString("N");
+            string temporaryAudioName = $".hitthekit-bind-{token}{extension}";
+            string temporaryAudio = Path.Combine(folder, temporaryAudioName);
+            string temporaryManifest = Path.Combine(folder, $".hitthekit-bind-{token}.json");
+            string backupManifest = Path.Combine(folder, $".hitthekit-bind-{token}.backup");
+            bool audioPublished = false;
+            try
+            {
+                File.Copy(source, temporaryAudio, false);
+                string validationManifest = Manifest(song, temporaryAudioName);
+                SongLibraryEntry validation = new SongLibraryDiscovery().Parse(
+                    validationManifest,
+                    folder,
+                    SongLibraryOrigin.UserFolder);
+                if (!validation.IsPlayable)
+                    throw new SongAudioBindingException("The selected audio does not complete this chart.");
+
+                File.Move(temporaryAudio, destinationAudio);
+                audioPublished = true;
+                string finalManifest = Manifest(song, audioName);
+                SongLibraryEntry published = new SongLibraryDiscovery().Parse(
+                    finalManifest,
+                    folder,
+                    SongLibraryOrigin.UserFolder);
+                if (!published.IsPlayable)
+                    throw new SongAudioBindingException("The local audio binding did not produce a playable song.");
+
+                File.WriteAllText(temporaryManifest, finalManifest, Utf8WithoutBom);
+                File.Replace(temporaryManifest, manifestPath, backupManifest);
+                TryDelete(backupManifest);
+                return new SongAudioBindingResult(published, source);
+            }
+            catch (SongAudioBindingException)
+            {
+                Cleanup(temporaryAudio, temporaryManifest, backupManifest, destinationAudio, audioPublished);
+                throw;
+            }
+            catch (Exception exception)
+            {
+                Cleanup(temporaryAudio, temporaryManifest, backupManifest, destinationAudio, audioPublished);
+                throw new SongAudioBindingException("The local audio binding could not be completed.", exception);
+            }
+        }
+
+        private static void ValidateSongBoundary(SongLibraryEntry song, string root, string folder)
+        {
+            if (!Directory.Exists(root) || !Directory.Exists(folder) || IsLink(folder))
+                throw new SongAudioBindingException("The imported song folder is unavailable or linked.");
+            DirectoryInfo parent = Directory.GetParent(folder);
+            if (parent == null || !string.Equals(Path.GetFullPath(parent.FullName), root, StringComparison.Ordinal) ||
+                !string.Equals(Path.GetFileName(folder), song.Id, StringComparison.Ordinal))
+                throw new SongAudioBindingException("The song folder is outside the configured user library.");
+        }
+
+        private static string Manifest(SongLibraryEntry song, string audioFileName)
+        {
+            var fields = new List<string>
+            {
+                "  \"schemaVersion\": 1",
+                $"  \"id\": \"{Escape(song.Id)}\"",
+                $"  \"title\": \"{Escape(song.Title)}\"",
+                $"  \"artist\": \"{Escape(song.Artist)}\""
+            };
+            AddOptional(fields, "album", song.Album);
+            AddOptional(fields, "genre", song.Genre);
+            if (song.Year.HasValue) fields.Add($"  \"year\": {song.Year.Value}");
+            if (song.Bpm.HasValue)
+                fields.Add($"  \"bpm\": {song.Bpm.Value.ToString("0.#########", CultureInfo.InvariantCulture)}");
+            if (song.Bars.HasValue) fields.Add($"  \"bars\": {song.Bars.Value}");
+            if (song.BeatsPerBar.HasValue) fields.Add($"  \"beatsPerBar\": {song.BeatsPerBar.Value}");
+            AddOptional(fields, "difficultyHint", song.DifficultyHint);
+            fields.Add($"  \"sortOrder\": {song.SortOrder}");
+            fields.Add("  \"audioAvailability\": \"available\"");
+            fields.Add($"  \"audioFile\": \"{Escape(audioFileName)}\"");
+            fields.Add("  \"chartAvailability\": \"available\"");
+            fields.Add($"  \"chartFile\": \"{Escape(Path.GetFileName(song.ChartPath))}\"");
+            return "{\n" + string.Join(",\n", fields) + "\n}\n";
+        }
+
+        private static void AddOptional(ICollection<string> fields, string name, string value)
+        {
+            if (!string.IsNullOrWhiteSpace(value)) fields.Add($"  \"{name}\": \"{Escape(value)}\"");
+        }
+
+        private static string Escape(string value) => value
+            .Replace("\\", "\\\\")
+            .Replace("\"", "\\\"")
+            .Replace("\r", "\\r")
+            .Replace("\n", "\\n");
+
+        private static bool IsLink(string path) =>
+            (File.GetAttributes(path) & FileAttributes.ReparsePoint) != 0;
+
+        private static void Cleanup(
+            string temporaryAudio,
+            string temporaryManifest,
+            string backupManifest,
+            string destinationAudio,
+            bool audioPublished)
+        {
+            TryDelete(temporaryAudio);
+            TryDelete(temporaryManifest);
+            TryDelete(backupManifest);
+            if (audioPublished) TryDelete(destinationAudio);
+        }
+
+        private static void TryDelete(string path)
+        {
+            try { if (File.Exists(path)) File.Delete(path); }
+            catch { /* Cleanup must not hide the structured binding failure. */ }
+        }
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs.meta
new file mode 100644
index 0000000..df7459b
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongAudioBinding.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 21dc65bdb1474ee58da1d9e259e0abf4
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs
index 8472536..0df7c99 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/SongLibrary.cs
@@ -107,6 +107,12 @@ internal SongLibraryEntry(
             AudioAvailability == SongAudioAvailability.Available &&
             !string.IsNullOrWhiteSpace(AudioPath) &&
             Bpm.HasValue && Bars.HasValue && BeatsPerBar.HasValue;
+        public bool CanBindAudio =>
+            Origin == SongLibraryOrigin.UserFolder &&
+            AudioAvailability == SongAudioAvailability.Missing &&
+            ChartAvailability == SongChartAvailability.Available &&
+            !string.IsNullOrWhiteSpace(ChartPath) &&
+            Bpm.HasValue && Bars.HasValue && BeatsPerBar.HasValue;
     }
 
     public sealed class SongLibraryRoot
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
index bff02d9..caa80bb 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/MainMenu/MainMenuController.cs
@@ -31,6 +31,7 @@ public sealed class MainMenuController : MonoBehaviour
         private VisualElement settingsOverlay;
         private VisualElement onboardingOverlay;
         private VisualElement chartAudioImportOverlay;
+        private VisualElement songAudioBindingOverlay;
         private Label eyebrow;
         private Label status;
         private Label learnHeading;
@@ -69,6 +70,7 @@ public sealed class MainMenuController : MonoBehaviour
         private Button songSpeedFullButton;
         private Button songPlayButton;
         private Button songRecordButton;
+        private Button songBindAudioButton;
         private Button songRefreshButton;
         private Button songFolderButton;
         private Button songBackButton;
@@ -82,6 +84,11 @@ public sealed class MainMenuController : MonoBehaviour
         private Label chartAudioErrorLabel;
         private Button chartAudioStartButton;
         private Button chartAudioCancelButton;
+        private Label songAudioBindingSongLabel;
+        private Label songAudioBindingFileLabel;
+        private Label songAudioBindingErrorLabel;
+        private Button songAudioBindingConfirmButton;
+        private Button songAudioBindingCancelButton;
         private ScrollView learnList;
         private Label learnProgressCount;
         private Label learnProgressAccuracy;
@@ -163,6 +170,8 @@ public sealed class MainMenuController : MonoBehaviour
         private string selectedSongId;
         private string selectedSongDifficulty;
         private string pendingChartAudioPath;
+        private string pendingSongAudioPath;
+        private string pendingSongAudioId;
         private double selectedSongSpeed = 1.0;
         private GameplayLessonId selectedLesson = GameplayLessonId.FirstPulse;
         private double selectedStudySpeed = 1.0;
@@ -203,6 +212,8 @@ public sealed class MainMenuController : MonoBehaviour
         public bool IsChartAudioImportVisible =>
             chartAudioImportOverlay != null && chartAudioImportOverlay.resolvedStyle.display != DisplayStyle.None;
         public string PendingChartAudioPath => pendingChartAudioPath;
+        public bool IsSongAudioBindingVisible =>
+            songAudioBindingOverlay != null && songAudioBindingOverlay.resolvedStyle.display != DisplayStyle.None;
 
         private void Awake()
         {
@@ -439,6 +450,7 @@ private void TryBind()
             songSpeedFullButton = Required<Button>(root, "song-speed-full");
             songPlayButton = Required<Button>(root, "song-play-button");
             songRecordButton = Required<Button>(root, "song-record-button");
+            songBindAudioButton = Required<Button>(root, "song-bind-audio-button");
             songRefreshButton = Required<Button>(root, "song-refresh-button");
             songFolderButton = Required<Button>(root, "song-folder-button");
             songBackButton = Required<Button>(root, "song-back-button");
@@ -453,6 +465,12 @@ private void TryBind()
             chartAudioErrorLabel = Required<Label>(root, "chart-audio-error");
             chartAudioStartButton = Required<Button>(root, "chart-audio-start");
             chartAudioCancelButton = Required<Button>(root, "chart-audio-cancel");
+            songAudioBindingOverlay = Required<VisualElement>(root, "song-audio-binding-overlay");
+            songAudioBindingSongLabel = Required<Label>(root, "song-audio-binding-song");
+            songAudioBindingFileLabel = Required<Label>(root, "song-audio-binding-file");
+            songAudioBindingErrorLabel = Required<Label>(root, "song-audio-binding-error");
+            songAudioBindingConfirmButton = Required<Button>(root, "song-audio-binding-confirm");
+            songAudioBindingCancelButton = Required<Button>(root, "song-audio-binding-cancel");
             learnList = Required<ScrollView>(root, "learn-list");
             learnProgressCount = Required<Label>(root, "learn-progress-count");
             learnProgressAccuracy = Required<Label>(root, "learn-progress-accuracy");
@@ -547,12 +565,15 @@ private void TryBind()
             songSpeedFullButton.clicked += SelectFullSongSpeed;
             songPlayButton.clicked += StartSelectedSongFromButton;
             songRecordButton.clicked += StartChartCreatorFromButton;
+            songBindAudioButton.clicked += PickAudioForSelectedSong;
             songRefreshButton.clicked += RefreshSongLibrary;
             songFolderButton.clicked += OpenUserSongFolder;
             songBackButton.clicked += CloseSongLibrary;
             songImportAudioButton.clicked += PickChartAuthoringAudio;
             chartAudioStartButton.clicked += ImportAudioAndStartChartCreatorFromButton;
             chartAudioCancelButton.clicked += CancelChartAuthoringAudio;
+            songAudioBindingConfirmButton.clicked += ConfirmSongAudioBindingFromButton;
+            songAudioBindingCancelButton.clicked += CancelSongAudioBinding;
             learnSpeedHalfButton.clicked += SelectHalfSpeed;
             learnSpeedThreeQuarterButton.clicked += SelectThreeQuarterSpeed;
             learnSpeedFullButton.clicked += SelectFullSpeed;
@@ -617,6 +638,7 @@ private void TryBind()
             settingsVisible = false;
             SetOverlay(settingsOverlay, false);
             SetOverlay(chartAudioImportOverlay, false);
+            SetOverlay(songAudioBindingOverlay, false);
             onboardingVisible = !PlayerPreferencesRuntime.Current.Snapshot.FirstRunCompleted;
             SetOverlay(onboardingOverlay, onboardingVisible);
             if (session.ReturnTarget == GameplayReturnTarget.LearningPath)
@@ -660,12 +682,15 @@ private void Unbind()
             songSpeedFullButton.clicked -= SelectFullSongSpeed;
             songPlayButton.clicked -= StartSelectedSongFromButton;
             songRecordButton.clicked -= StartChartCreatorFromButton;
+            songBindAudioButton.clicked -= PickAudioForSelectedSong;
             songRefreshButton.clicked -= RefreshSongLibrary;
             songFolderButton.clicked -= OpenUserSongFolder;
             songBackButton.clicked -= CloseSongLibrary;
             songImportAudioButton.clicked -= PickChartAuthoringAudio;
             chartAudioStartButton.clicked -= ImportAudioAndStartChartCreatorFromButton;
             chartAudioCancelButton.clicked -= CancelChartAuthoringAudio;
+            songAudioBindingConfirmButton.clicked -= ConfirmSongAudioBindingFromButton;
+            songAudioBindingCancelButton.clicked -= CancelSongAudioBinding;
             learnSpeedHalfButton.clicked -= SelectHalfSpeed;
             learnSpeedThreeQuarterButton.clicked -= SelectThreeQuarterSpeed;
             learnSpeedFullButton.clicked -= SelectFullSpeed;
@@ -893,6 +918,79 @@ private void CancelChartAuthoringAudio()
             SetOverlay(chartAudioImportOverlay, false);
         }
 
+        private void PickAudioForSelectedSong()
+        {
+            try
+            {
+                SongLibraryEntry song = SelectedSong();
+                if (song == null || !song.CanBindAudio)
+                    throw new InvalidOperationException("Select an imported chart awaiting local audio.");
+                string path = new MacOsChartAuthoringAudioPicker().PickAudioFile();
+                if (!string.IsNullOrWhiteSpace(path)) BeginSongAudioBinding(path);
+            }
+            catch (Exception exception)
+            {
+                songLibraryDiagnostic.text = (Language == MainMenuLanguage.Italian
+                    ? "ASSOCIAZIONE AUDIO NON RIUSCITA · "
+                    : "AUDIO BINDING FAILED · ") + exception.Message;
+            }
+        }
+
+        public void BeginSongAudioBinding(string sourceAudioPath)
+        {
+            SongLibraryEntry song = SelectedSong();
+            if (song == null || !song.CanBindAudio)
+                throw new InvalidOperationException("Select an imported chart awaiting local audio.");
+            pendingSongAudioPath = ChartAuthoringAudioImporter.ValidateSource(sourceAudioPath);
+            pendingSongAudioId = song.Id;
+            songAudioBindingSongLabel.text = $"{song.Title.ToUpperInvariant()} · {song.Artist.ToUpperInvariant()}";
+            songAudioBindingFileLabel.text = Path.GetFileName(pendingSongAudioPath);
+            songAudioBindingErrorLabel.text = Language == MainMenuLanguage.Italian
+                ? "Conferma di avere il diritto di usare questa copia audio locale."
+                : "Confirm that you may use this local audio copy.";
+            SetOverlay(songAudioBindingOverlay, true);
+        }
+
+        public bool ConfirmSongAudioBinding(string libraryRoot = null)
+        {
+            try
+            {
+                SongLibraryEntry song = songLibrary?.Songs.FirstOrDefault(value =>
+                    string.Equals(value.Id, pendingSongAudioId, StringComparison.Ordinal));
+                if (song == null || string.IsNullOrWhiteSpace(pendingSongAudioPath))
+                    throw new InvalidOperationException("Choose a song and an audio file first.");
+                new SongAudioBindingService().Bind(
+                    song,
+                    pendingSongAudioPath,
+                    string.IsNullOrWhiteSpace(libraryRoot) ? SongLibraryRuntime.UserRoot : libraryRoot);
+                selectedSongId = song.Id;
+                pendingSongAudioPath = null;
+                pendingSongAudioId = null;
+                SetOverlay(songAudioBindingOverlay, false);
+                RefreshSongLibrary();
+                songLibraryDiagnostic.text = Language == MainMenuLanguage.Italian
+                    ? "AUDIO LOCALE ASSOCIATO · BRANO PRONTO"
+                    : "LOCAL AUDIO BOUND · SONG READY";
+                return SelectedSong()?.IsPlayable == true;
+            }
+            catch (Exception exception)
+            {
+                songAudioBindingErrorLabel.text = (Language == MainMenuLanguage.Italian
+                    ? "ASSOCIAZIONE NON RIUSCITA · "
+                    : "BINDING FAILED · ") + exception.Message;
+                return false;
+            }
+        }
+
+        private void ConfirmSongAudioBindingFromButton() => ConfirmSongAudioBinding();
+
+        private void CancelSongAudioBinding()
+        {
+            pendingSongAudioPath = null;
+            pendingSongAudioId = null;
+            SetOverlay(songAudioBindingOverlay, false);
+        }
+
         private static bool TryParseDouble(string value, out double result)
         {
             if (double.TryParse(value, NumberStyles.Float, CultureInfo.CurrentCulture, out result) && result > 0)
@@ -1389,6 +1487,8 @@ private void RenderSongLibrary()
                     : "ADD A FOLDER CONTAINING song.json.";
                 songPlayButton.SetEnabled(false);
                 songRecordButton.SetEnabled(false);
+                songBindAudioButton.SetEnabled(false);
+                songBindAudioButton.style.display = DisplayStyle.None;
                 songPlayButton.text = italian ? "NESSUN BRANO" : "NO SONGS";
                 songRecordButton.text = italian ? "REGISTRA CHART" : "RECORD CHART";
                 SetSongSpeedControlsEnabled(false);
@@ -1449,6 +1549,9 @@ private void RenderSongLibrary()
             songRecordButton.text = selected.CanAuthorChart && !selected.IsPlayable
                 ? (italian ? "REGISTRA PRIMA CHART" : "RECORD FIRST CHART")
                 : (italian ? "REGISTRA CHART" : "RECORD CHART");
+            songBindAudioButton.style.display = selected.CanBindAudio ? DisplayStyle.Flex : DisplayStyle.None;
+            songBindAudioButton.SetEnabled(selected.CanBindAudio);
+            songBindAudioButton.text = italian ? "ASSOCIA AUDIO LOCALE" : "BIND LOCAL AUDIO";
             songRefreshButton.text = italian ? "AGGIORNA LIBRERIA" : "REFRESH LIBRARY";
             songFolderButton.text = italian ? "APRI CARTELLA BRANI" : "OPEN SONG FOLDER";
             songBackButton.text = italian ? "INDIETRO" : "BACK";
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
index 821bbe1..124f572 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
@@ -100,6 +100,53 @@ public void Quantization_is_non_destructive_and_uses_the_selected_musical_grid()
             Assert.That(draft.Hits.Single().TimeSeconds, Is.EqualTo(0.13), "Quantization must not mutate the raw take.");
         }
 
+        [Test]
+        public void Visual_editor_updates_adds_and_deletes_individual_notes_without_mutating_the_raw_take()
+        {
+            var session = new ChartRecordingSession(8);
+            session.Record(Input(DrumPad.Kick, 1));
+            session.Record(Input(DrumPad.Snare, 2));
+            ChartRecordingDraft raw = session.Finish();
+            var editor = new ChartDraftEditor(raw);
+
+            int moved = editor.Update(0, 2.5, DrumPad.Ride);
+            int added = editor.Add(1.5, DrumPad.HiHat, 88);
+            editor.Delete(0);
+            ChartRecordingDraft edited = editor.BuildDraft();
+
+            Assert.That(moved, Is.EqualTo(1), "Moving the first note after the snare must re-sort the visual timeline.");
+            Assert.That(added, Is.EqualTo(0));
+            Assert.That(raw.Hits.Select(hit => (hit.TimeSeconds, hit.Pad)), Is.EqualTo(new[]
+            {
+                (1d, DrumPad.Kick),
+                (2d, DrumPad.Snare)
+            }), "The captured raw take is immutable.");
+            Assert.That(edited.Hits.Select(hit => (hit.TimeSeconds, hit.Pad)), Is.EqualTo(new[]
+            {
+                (2d, DrumPad.Snare),
+                (2.5d, DrumPad.Ride)
+            }));
+            Assert.That(new ChartLoader().Load(
+                ChartCreatorJson.Serialize(edited, "easy", 120, ChartQuantization.None), "easy").Notes,
+                Has.Count.EqualTo(2));
+        }
+
+        [Test]
+        public void Visual_editor_rejects_invalid_indices_times_pads_and_velocity()
+        {
+            var session = new ChartRecordingSession(4);
+            session.Record(Input(DrumPad.Kick, 1));
+            var editor = new ChartDraftEditor(session.Finish());
+
+            Assert.Throws<ArgumentOutOfRangeException>(() => editor.Update(-1, 1, DrumPad.Kick));
+            Assert.Throws<ArgumentOutOfRangeException>(() => editor.Update(0, -0.01, DrumPad.Kick));
+            Assert.Throws<ArgumentOutOfRangeException>(() => editor.Update(0, 4.01, DrumPad.Kick));
+            Assert.Throws<ArgumentOutOfRangeException>(() => editor.Update(0, 1, (DrumPad)999));
+            Assert.Throws<ArgumentOutOfRangeException>(() => editor.Add(1, DrumPad.Snare, 128));
+            Assert.Throws<ArgumentOutOfRangeException>(() => editor.Delete(2));
+            Assert.That(editor.Notes, Has.Count.EqualTo(1));
+        }
+
         [Test]
         public void Export_is_atomic_chart_only_and_discovered_as_unavailable_until_audio_is_bound()
         {
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs
index 7032682..6fd7668 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/HtkSongPackageTests.cs
@@ -57,6 +57,60 @@ public void Chart_only_package_round_trip_imports_the_real_song_formats_without_
                 Is.EqualTo(File.ReadAllText(exported.ChartPath)));
         }
 
+        [Test]
+        public void Imported_chart_can_bind_an_authorized_local_audio_copy_without_changing_the_package_or_source()
+        {
+            ChartCreatorExportResult exported = ExportTake();
+            string incoming = Path.Combine(importRoot, Path.GetFileName(exported.PackagePath));
+            File.Copy(exported.PackagePath, incoming);
+            new HtkSongPackageService().ImportChartOnlyPackage(incoming, importRoot);
+            SongLibraryEntry imported = DiscoverImportedSong();
+            string source = Path.Combine(root, "authorized.wav");
+            WriteWave(source);
+            byte[] sourceBefore = File.ReadAllBytes(source);
+            byte[] packageBefore = File.ReadAllBytes(incoming);
+
+            SongAudioBindingResult result = new SongAudioBindingService().Bind(imported, source, importRoot);
+            SongLibraryEntry rebound = DiscoverImportedSong();
+
+            Assert.That(imported.CanBindAudio, Is.True);
+            Assert.That(result.Song.IsPlayable, Is.True);
+            Assert.That(rebound.IsPlayable, Is.True);
+            Assert.That(rebound.CanBindAudio, Is.False);
+            Assert.That(Path.GetFileName(rebound.AudioPath), Is.EqualTo("source-audio.wav"));
+            Assert.That(Directory.GetFiles(rebound.FolderPath).Select(Path.GetFileName), Is.EquivalentTo(new[]
+            {
+                "song.json", "notes.json", "source-audio.wav"
+            }));
+            Assert.That(File.ReadAllBytes(source), Is.EqualTo(sourceBefore));
+            Assert.That(File.ReadAllBytes(incoming), Is.EqualTo(packageBefore),
+                "Local binding must never rewrite the portable chart-only package.");
+            Assert.That(File.ReadAllText(Path.Combine(rebound.FolderPath, "song.json")),
+                Does.Not.Contain(Path.GetFullPath(source)));
+            Assert.That(Directory.GetFiles(rebound.FolderPath, ".hitthekit-bind-*"), Is.Empty);
+        }
+
+        [Test]
+        public void Audio_binding_rejects_a_song_outside_the_declared_user_root_without_partial_files()
+        {
+            ChartCreatorExportResult exported = ExportTake();
+            string incoming = Path.Combine(importRoot, Path.GetFileName(exported.PackagePath));
+            File.Copy(exported.PackagePath, incoming);
+            new HtkSongPackageService().ImportChartOnlyPackage(incoming, importRoot);
+            SongLibraryEntry imported = DiscoverImportedSong();
+            string source = Path.Combine(root, "authorized.wav");
+            WriteWave(source);
+            string differentRoot = Path.Combine(root, "different-root");
+            Directory.CreateDirectory(differentRoot);
+
+            SongAudioBindingException error = Assert.Throws<SongAudioBindingException>(() =>
+                new SongAudioBindingService().Bind(imported, source, differentRoot));
+
+            Assert.That(error.Message, Does.Contain("outside"));
+            Assert.That(Directory.GetFiles(imported.FolderPath).Select(Path.GetFileName),
+                Is.EquivalentTo(new[] { "song.json", "notes.json" }));
+        }
+
         [Test]
         public void Inbox_import_is_deterministic_idempotent_and_preserves_the_portable_file()
         {
@@ -174,6 +228,25 @@ private ChartCreatorExportResult ExportTake()
                 new DateTimeOffset(2026, 8, 19, 12, 0, 0, TimeSpan.Zero));
         }
 
+        private SongLibraryEntry DiscoverImportedSong() => new SongLibraryDiscovery().Discover(new[]
+        {
+            new SongLibraryRoot(importRoot, SongLibraryOrigin.UserFolder)
+        }).Songs.Single();
+
+        private static void WriteWave(string path)
+        {
+            byte[] wave =
+            {
+                0x52, 0x49, 0x46, 0x46, 0x26, 0x00, 0x00, 0x00,
+                0x57, 0x41, 0x56, 0x45, 0x66, 0x6d, 0x74, 0x20,
+                0x10, 0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00,
+                0x40, 0x1f, 0x00, 0x00, 0x80, 0x3e, 0x00, 0x00,
+                0x02, 0x00, 0x10, 0x00, 0x64, 0x61, 0x74, 0x61,
+                0x02, 0x00, 0x00, 0x00, 0x00, 0x00
+            };
+            File.WriteAllBytes(path, wave);
+        }
+
         private static string ValidManifest(string id) =>
             "{\"schemaVersion\":1," +
             $"\"id\":\"{id}\",\"title\":\"Song\",\"artist\":\"Local Player\"," +
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
index 7c96058..7a76c79 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/MainMenuPlayModeTests.cs
@@ -51,6 +51,8 @@ public IEnumerator Main_menu_scene_loads_stage_command_with_accessible_destinati
             Assert.That(document.rootVisualElement.Q<Button>("menu-play").focusable, Is.True);
             Assert.That(document.rootVisualElement.Q<Button>("menu-learn").focusable, Is.True);
             Assert.That(document.rootVisualElement.Q<Button>("menu-setup").focusable, Is.True);
+            Assert.That(document.rootVisualElement.Q<Button>("song-bind-audio-button"), Is.Not.Null);
+            Assert.That(document.rootVisualElement.Q<VisualElement>("song-audio-binding-overlay"), Is.Not.Null);
             Assert.That(controller.IsLearnOverlayVisible, Is.False);
             Assert.That(controller.IsSettingsOverlayVisible, Is.False);
             MainMenuStageEnvironment stage = controller.StageEnvironment;
@@ -201,6 +203,13 @@ public IEnumerator Chart_creator_launches_the_real_gameplay_session_for_the_sele
             Assert.That(gameplay.CurrentSession.SpeedMultiplier, Is.EqualTo(0.6));
             Assert.That(gameplay.GetComponent<UIDocument>().rootVisualElement
                 .Q<VisualElement>("chart-creator-results"), Is.Not.Null);
+            VisualElement gameplayRoot = gameplay.GetComponent<UIDocument>().rootVisualElement;
+            Assert.That(gameplayRoot.Q<ListView>("chart-note-list"), Is.Not.Null);
+            Assert.That(gameplayRoot.Q<TextField>("chart-note-time"), Is.Not.Null);
+            Assert.That(gameplayRoot.Q<DropdownField>("chart-note-pad"), Is.Not.Null);
+            Assert.That(gameplayRoot.Q<Button>("chart-note-add"), Is.Not.Null);
+            Assert.That(gameplayRoot.Q<Button>("chart-note-apply"), Is.Not.Null);
+            Assert.That(gameplayRoot.Q<Button>("chart-note-delete"), Is.Not.Null);
             LogAssert.NoUnexpectedReceived();
         }
 
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
index db59796..b8a60fa 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
@@ -509,6 +509,7 @@
 }
 
 .results-dialog { width: 720px; }
+.result-performance-panel { width: 100%; align-items: center; }
 .run-dialog-title { font-size: 34px; -unity-font-style: bold; letter-spacing: 3px; }
 .run-dialog-copy { color: var(--muted); margin-top: 9px; margin-bottom: 20px; }
 .run-primary-button,
@@ -541,6 +542,19 @@
 .chart-creator-actions { margin-top: 10px; flex-direction: row; justify-content: center; }
 .chart-save-button { width: 170px; min-height: 38px; margin: 0 4px; }
 .chart-creator-status { min-height: 20px; margin-top: 8px; color: rgb(78, 221, 137); font-size: 10px; -unity-font-style: bold; white-space: normal; -unity-text-align: middle-center; }
+.chart-note-editor { height: 250px; margin-top: 10px; flex-direction: row; }
+.chart-note-list { width: 48%; height: 100%; border-width: 1px; border-color: rgba(74, 138, 168, 0.7); background-color: rgba(2, 10, 18, 0.9); }
+.chart-note-list .unity-list-view__item { padding-left: 8px; color: white; border-bottom-width: 1px; border-bottom-color: rgba(74, 138, 168, 0.28); }
+.chart-note-list .unity-collection-view__item--selected { background-color: rgba(24, 151, 190, 0.75); }
+.chart-note-controls { width: 52%; padding-left: 12px; }
+.chart-note-selection { min-height: 22px; color: rgb(91, 224, 255); font-size: 11px; -unity-font-style: bold; }
+.chart-note-fields { margin-top: 5px; }
+.chart-note-time, .chart-note-pad { margin-top: 5px; color: white; }
+.chart-note-time .unity-text-input, .chart-note-pad .unity-base-field__input { background-color: rgba(9, 24, 36, 0.98); border-width: 1px; border-color: rgb(52, 86, 108); color: white; }
+.chart-note-buttons { margin-top: 8px; flex-direction: row; }
+.chart-note-button { min-width: 88px; height: 34px; min-height: 34px; margin: 0 3px; font-size: 9px; }
+.chart-note-delete { border-color: rgb(241, 91, 104); color: rgb(255, 148, 158); }
+.chart-note-status { min-height: 28px; margin-top: 8px; color: rgb(255, 190, 84); font-size: 9px; white-space: normal; }
 .gameplay--high-contrast .highway-shell,
 .gameplay--high-contrast .results-dialog,
 .gameplay--high-contrast .run-dialog { border-color: white; background-color: rgba(0, 0, 0, 0.97); }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
index 86fdbd8..a025399 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
@@ -111,20 +111,38 @@
         <ui:VisualElement name="results-overlay" class="run-overlay" style="display: none;">
             <ui:VisualElement class="results-dialog">
                 <ui:Label text="BRANO COMPLETATO" class="eyebrow results-eyebrow" />
-                <ui:Label name="result-rank" text="S" class="result-rank" />
-                <ui:VisualElement class="results-metrics">
-                    <ui:VisualElement class="result-metric"><ui:Label text="SCORE" class="metric-label" /><ui:Label name="result-score" text="0" class="result-value" /></ui:VisualElement>
-                    <ui:VisualElement class="result-metric"><ui:Label text="ACCURACY" class="metric-label" /><ui:Label name="result-accuracy" text="100.0%" class="result-value" /></ui:VisualElement>
-                    <ui:VisualElement class="result-metric"><ui:Label text="MAX COMBO" class="metric-label" /><ui:Label name="result-combo" text="0" class="result-value" /></ui:VisualElement>
+                <ui:VisualElement name="result-performance-panel" class="result-performance-panel">
+                    <ui:Label name="result-rank" text="S" class="result-rank" />
+                    <ui:VisualElement class="results-metrics">
+                        <ui:VisualElement class="result-metric"><ui:Label text="SCORE" class="metric-label" /><ui:Label name="result-score" text="0" class="result-value" /></ui:VisualElement>
+                        <ui:VisualElement class="result-metric"><ui:Label text="ACCURACY" class="metric-label" /><ui:Label name="result-accuracy" text="100.0%" class="result-value" /></ui:VisualElement>
+                        <ui:VisualElement class="result-metric"><ui:Label text="MAX COMBO" class="metric-label" /><ui:Label name="result-combo" text="0" class="result-value" /></ui:VisualElement>
+                    </ui:VisualElement>
+                    <ui:Label name="result-breakdown" text="PERFECT 0   GOOD 0   EARLY/LATE 0   MISS 0" class="result-breakdown" />
+                    <ui:Label name="result-practice" text="FOCUS: COMPLETA UNA SESSIONE" class="result-practice" />
+                    <ui:Label name="result-calibration" text="CALIBRAZIONE: SERVONO 8 COLPI VALIDI" class="result-calibration" />
+                    <ui:Button name="result-apply-calibration" text="APPLICA CALIBRAZIONE" class="run-secondary-button result-calibration-button" />
                 </ui:VisualElement>
-                <ui:Label name="result-breakdown" text="PERFECT 0   GOOD 0   EARLY/LATE 0   MISS 0" class="result-breakdown" />
-                <ui:Label name="result-practice" text="FOCUS: COMPLETA UNA SESSIONE" class="result-practice" />
-                <ui:Label name="result-calibration" text="CALIBRAZIONE: SERVONO 8 COLPI VALIDI" class="result-calibration" />
-                <ui:Button name="result-apply-calibration" text="APPLICA CALIBRAZIONE" class="run-secondary-button result-calibration-button" />
                 <ui:VisualElement name="chart-creator-results" class="chart-creator-results" style="display: none;">
                     <ui:Label text="REVISIONE TAKE" class="eyebrow chart-creator-eyebrow" />
                     <ui:Label name="chart-creator-summary" text="0 COLPI REGISTRATI" class="chart-creator-summary" />
-                    <ui:Label text="L'audio non viene copiato. Salva la chart e usa il file .htksong per trasferirla su un altro computer." class="chart-creator-copy" />
+                    <ui:Label text="Seleziona una nota per correggere tempo o strumento. Il pacchetto .htksong resta senza audio." class="chart-creator-copy" />
+                    <ui:VisualElement class="chart-note-editor">
+                        <ui:ListView name="chart-note-list" class="chart-note-list" />
+                        <ui:VisualElement class="chart-note-controls">
+                            <ui:Label name="chart-note-selection" text="SELEZIONA UNA NOTA" class="chart-note-selection" />
+                            <ui:VisualElement class="chart-note-fields">
+                                <ui:TextField name="chart-note-time" label="TEMPO (s)" class="chart-note-time" />
+                                <ui:DropdownField name="chart-note-pad" label="STRUMENTO" class="chart-note-pad" />
+                            </ui:VisualElement>
+                            <ui:VisualElement class="chart-note-buttons">
+                                <ui:Button name="chart-note-add" text="AGGIUNGI" class="run-secondary-button chart-note-button" />
+                                <ui:Button name="chart-note-apply" text="APPLICA" class="run-primary-button chart-note-button" />
+                                <ui:Button name="chart-note-delete" text="ELIMINA" class="run-secondary-button chart-note-button chart-note-delete" />
+                            </ui:VisualElement>
+                            <ui:Label name="chart-note-status" class="chart-note-status" />
+                        </ui:VisualElement>
+                    </ui:VisualElement>
                     <ui:VisualElement class="chart-creator-actions">
                         <ui:Button name="chart-save-raw" text="SALVA RAW" class="run-secondary-button chart-save-button" />
                         <ui:Button name="chart-save-eighth" text="SALVA 1/8" class="run-secondary-button chart-save-button" />
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
index 820c724..e94cf22 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uss
@@ -1044,6 +1044,9 @@
 .chart-audio-error { min-height: 34px; margin-top: 12px; color: rgb(255, 178, 70); font-size: 11px; white-space: normal; }
 .chart-audio-actions { flex-direction: row; justify-content: flex-end; }
 .chart-audio-actions .modal-secondary, .chart-audio-actions .modal-primary { min-width: 190px; }
+.song-bind-audio-button { border-color: rgb(230, 145, 48); color: rgb(255, 191, 105); }
+.song-audio-binding-panel { width: 680px; min-height: 390px; padding: 30px 40px; }
+.song-audio-binding-song { margin-top: 18px; color: white; font-size: 18px; -unity-font-style: bold; white-space: normal; }
 
 .main-menu--compact .song-library-section { left: 6px; top: 8px; right: 6px; }
 .main-menu--compact .song-library-rail { width: 104px; min-width: 104px; }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
index 03677d5..9aa0934 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/MainMenu/MainMenu.uxml
@@ -116,6 +116,7 @@
                             <ui:VisualElement class="song-primary-actions">
                                 <ui:Button name="song-play-button" text="SUONA ORA" class="song-play-button" />
                                 <ui:Button name="song-record-button" text="REGISTRA CHART" class="song-record-button" />
+                                <ui:Button name="song-bind-audio-button" text="ASSOCIA AUDIO LOCALE" class="song-record-button song-bind-audio-button" style="display: none;" />
                             </ui:VisualElement>
                             <ui:Label text="INVIO O DOPPIO KICK" class="song-play-hint" />
                         </ui:VisualElement>
@@ -172,6 +173,21 @@
             </ui:VisualElement>
         </ui:VisualElement>
 
+        <ui:VisualElement name="song-audio-binding-overlay" class="modal-layer chart-audio-import-layer" style="display: none;">
+            <ui:VisualElement class="modal-panel song-audio-binding-panel">
+                <ui:Label text="PACCHETTO .HTKSONG" class="modal-eyebrow" />
+                <ui:Label text="ASSOCIA LA TUA COPIA AUDIO" class="chart-audio-import-title" />
+                <ui:Label name="song-audio-binding-song" class="song-audio-binding-song" />
+                <ui:Label name="song-audio-binding-file" class="chart-audio-file" />
+                <ui:Label text="Il file viene copiato nella cartella locale del brano. Non viene aggiunto né al pacchetto .htksong né al repository." class="chart-audio-import-copy" />
+                <ui:Label name="song-audio-binding-error" class="chart-audio-error" />
+                <ui:VisualElement class="modal-actions chart-audio-actions">
+                    <ui:Button name="song-audio-binding-cancel" text="ANNULLA" class="modal-secondary" />
+                    <ui:Button name="song-audio-binding-confirm" text="ASSOCIA E VERIFICA" class="modal-primary" />
+                </ui:VisualElement>
+            </ui:VisualElement>
+        </ui:VisualElement>
+
         <ui:VisualElement name="learn-overlay" class="learn-section">
             <ui:VisualElement class="learn-rail">
                 <ui:VisualElement class="learn-brand">

From 9bbaaf91a71394c61ef48505c7226992c1d6a831 Mon Sep 17 00:00:00 2001
From: Baron Luca <baron_luca@hotmail.it>
Date: Wed, 19 Aug 2026 16:05:15 +0200
Subject: [PATCH 5/5] feat(charts): add waveform and note expression editing

---
 docs/development/chart-creator.md             |  31 ++-
 src/HitTheKit.Core/ChartNote.cs               |  16 +-
 src/HitTheKit.Core/DrumArticulation.cs        |  66 +++++
 src/HitTheKit.Core/DrumHit.cs                 |  10 +-
 src/HitTheKit.Core/HitMatcher.cs              |   3 +-
 .../Runtime/Audio/DspSongClockPrototype.cs    |  24 ++
 .../HitTheKit/Runtime/Charts/ChartLoader.cs   |  42 ++-
 .../Runtime/Charts/ChartTimelinePrototype.cs  |   9 +-
 .../Runtime/Devices/MidiKitMappingEngine.cs   |  22 +-
 .../Runtime/Gameplay/ChartCreator.cs          |  47 +++-
 .../Runtime/Gameplay/ChartDraftEditor.cs      |  50 +++-
 .../Runtime/Gameplay/ChartWaveform.cs         | 257 ++++++++++++++++++
 .../Runtime/Gameplay/ChartWaveform.cs.meta    |  11 +
 .../Gameplay/GameplayHighwayController.cs     | 233 +++++++++++++++-
 .../Gameplay/GameplayKitVisualModel.cs        |  24 +-
 .../HitTheKit/Runtime/Input/DrumInputEvent.cs |   9 +-
 .../Runtime/Matching/HitMatchingSession.cs    |   2 +-
 .../Tests/EditMode/ChartCreatorTests.cs       |  81 +++++-
 .../Tests/EditMode/ChartLoaderTests.cs        |  37 +++
 .../Tests/EditMode/GameplayHighwayTests.cs    |  22 ++
 .../EditMode/MidiKitMappingEngineTests.cs     |  20 ++
 .../PlayMode/GameplayHighwayPlayModeTests.cs  |   4 +
 .../HitTheKit/UI/Gameplay/GameplayHighway.uss |  12 +-
 .../UI/Gameplay/GameplayHighway.uxml          |  15 +-
 tests/HitTheKit.Core.Tests/HitMatcherTests.cs |  41 +++
 25 files changed, 1052 insertions(+), 36 deletions(-)
 create mode 100644 src/HitTheKit.Core/DrumArticulation.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs
 create mode 100644 src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs.meta

diff --git a/docs/development/chart-creator.md b/docs/development/chart-creator.md
index 6e2038b..07753a0 100644
--- a/docs/development/chart-creator.md
+++ b/docs/development/chart-creator.md
@@ -17,8 +17,10 @@ timeline.
    current chart only as a playback reference.
 4. Play during the normal count-in and backing track. Hits before song time zero
    or beyond the declared song duration are ignored.
-5. At the result screen, review the captured notes in the visual editor. Select
-   a note to change its time or drum pad, add missing notes, or delete unwanted
+5. At the result screen, review the captured notes against the bounded waveform.
+   Drag its playhead to scrub the source timeline, zoom around a passage, and
+   preview audio from the selected time. Select a note to change its time, drum
+   pad, velocity or physical articulation, add missing notes, or delete unwanted
    notes. The original recorded take remains unchanged in memory.
 6. Save the edited timing as recorded, or quantize the edited draft
    non-destructively to an eighth- or sixteenth-note grid.
@@ -69,13 +71,28 @@ The exported title is marked `Recorded Take` and the difficulty hint says that
 the performance must be reviewed before sharing. This is a captured performance,
 not a claim of authoritative transcription.
 
+## Note expression
+
+Schema v1 remains backward compatible: `velocity` and `articulation` are
+optional note properties. A legacy note without them keeps unknown velocity and
+the `default` articulation wildcard. Newly recorded/exported notes preserve
+velocity; non-default articulations use explicit identifiers such as `rim`,
+`bell`, `bow`, `edge`, `open`, or `pedal`.
+
+Known articulations are validated against the selected pad. An explicit Ride
+Bell target, for example, matches only a bell hit and highlights the bell zone
+of the instructional kit. Changing a note to an incompatible pad resets its
+articulation to the backward-compatible default rather than inventing a zone.
+
+The waveform is an editor envelope, not a second clock or audio importer. It is
+sampled from the already-loaded `AudioClip` into a bounded 512-point model, and
+preview playback reuses the existing `DspSongClockPrototype` audio source. The
+chart timing remains source-time based and the recorded take remains immutable.
+
 ## Current foundation limits
 
-- The visual editor supports individual note time/pad changes, additions and
-  deletions. Waveform scrubbing and articulation/velocity authoring are future
-  editing tools.
-- The schema currently stores pad and time. Velocity and articulation remain in
-  the in-memory take but schema v1 does not serialize them.
+- The waveform provides envelope scrubbing, zoom and preview; it is not yet a
+  sample-accurate destructive audio editor.
 - The native picker currently targets macOS. WAV and OGG are supported; MP3 is
   intentionally rejected by the production loader.
 - The author must enter BPM, bars and meter explicitly. Unknown timing never
diff --git a/src/HitTheKit.Core/ChartNote.cs b/src/HitTheKit.Core/ChartNote.cs
index 36d09f2..cba7952 100644
--- a/src/HitTheKit.Core/ChartNote.cs
+++ b/src/HitTheKit.Core/ChartNote.cs
@@ -4,7 +4,11 @@ namespace HitTheKit.Core
 {
     public sealed class ChartNote
     {
-        public ChartNote(double timeSeconds, DrumPad pad)
+        public ChartNote(
+            double timeSeconds,
+            DrumPad pad,
+            int? velocity = null,
+            DrumArticulation articulation = DrumArticulation.Default)
         {
             if (!IsFinite(timeSeconds) || timeSeconds < 0)
             {
@@ -13,14 +17,24 @@ public ChartNote(double timeSeconds, DrumPad pad)
                     "A chart note time must be finite and non-negative.");
             }
 
+            if (velocity.HasValue && (velocity.Value < 1 || velocity.Value > 127))
+                throw new ArgumentOutOfRangeException(nameof(velocity), "Target velocity must be between 1 and 127.");
+            DrumArticulationValidator.EnsureValid(pad, articulation);
+
             TimeSeconds = timeSeconds;
             Pad = pad;
+            Velocity = velocity;
+            Articulation = articulation;
         }
 
         public double TimeSeconds { get; }
 
         public DrumPad Pad { get; }
 
+        public int? Velocity { get; }
+
+        public DrumArticulation Articulation { get; }
+
         private static bool IsFinite(double value)
         {
             return !double.IsNaN(value) && !double.IsInfinity(value);
diff --git a/src/HitTheKit.Core/DrumArticulation.cs b/src/HitTheKit.Core/DrumArticulation.cs
new file mode 100644
index 0000000..c4bac2c
--- /dev/null
+++ b/src/HitTheKit.Core/DrumArticulation.cs
@@ -0,0 +1,66 @@
+using System;
+
+namespace HitTheKit.Core
+{
+    public enum DrumArticulation
+    {
+        Default,
+        Head,
+        Rim,
+        Bow,
+        Edge,
+        Bell,
+        Closed,
+        HalfOpen,
+        Open,
+        Pedal,
+        Choke
+    }
+
+    public static class DrumArticulationValidator
+    {
+        public static bool IsValid(DrumPad pad, DrumArticulation articulation)
+        {
+            if (!Enum.IsDefined(typeof(DrumPad), pad) ||
+                !Enum.IsDefined(typeof(DrumArticulation), articulation))
+                return false;
+            if (articulation == DrumArticulation.Default) return true;
+
+            switch (pad)
+            {
+                case DrumPad.Kick:
+                    return false;
+                case DrumPad.Snare:
+                case DrumPad.Tom1:
+                case DrumPad.Tom2:
+                case DrumPad.FloorTom:
+                    return articulation == DrumArticulation.Head || articulation == DrumArticulation.Rim;
+                case DrumPad.HiHat:
+                    return articulation == DrumArticulation.Bow ||
+                           articulation == DrumArticulation.Edge ||
+                           articulation == DrumArticulation.Closed ||
+                           articulation == DrumArticulation.HalfOpen ||
+                           articulation == DrumArticulation.Open ||
+                           articulation == DrumArticulation.Pedal ||
+                           articulation == DrumArticulation.Choke;
+                case DrumPad.Crash:
+                    return articulation == DrumArticulation.Bow ||
+                           articulation == DrumArticulation.Edge ||
+                           articulation == DrumArticulation.Choke;
+                case DrumPad.Ride:
+                    return articulation == DrumArticulation.Bow ||
+                           articulation == DrumArticulation.Edge ||
+                           articulation == DrumArticulation.Bell ||
+                           articulation == DrumArticulation.Choke;
+                default:
+                    return false;
+            }
+        }
+
+        public static void EnsureValid(DrumPad pad, DrumArticulation articulation)
+        {
+            if (!IsValid(pad, articulation))
+                throw new ArgumentException($"Articulation '{articulation}' is not valid for drum pad '{pad}'.");
+        }
+    }
+}
diff --git a/src/HitTheKit.Core/DrumHit.cs b/src/HitTheKit.Core/DrumHit.cs
index 88c8acf..1514ad7 100644
--- a/src/HitTheKit.Core/DrumHit.cs
+++ b/src/HitTheKit.Core/DrumHit.cs
@@ -4,7 +4,11 @@ namespace HitTheKit.Core
 {
     public readonly struct DrumHit
     {
-        public DrumHit(DrumPad pad, double timeSeconds, int velocity = 127)
+        public DrumHit(
+            DrumPad pad,
+            double timeSeconds,
+            int velocity = 127,
+            DrumArticulation articulation = DrumArticulation.Default)
         {
             if (double.IsNaN(timeSeconds) || double.IsInfinity(timeSeconds))
             {
@@ -20,9 +24,11 @@ public DrumHit(DrumPad pad, double timeSeconds, int velocity = 127)
                     "Velocity must be between 0 and 127.");
             }
 
+            DrumArticulationValidator.EnsureValid(pad, articulation);
             Pad = pad;
             TimeSeconds = timeSeconds;
             Velocity = velocity;
+            Articulation = articulation;
         }
 
         public DrumPad Pad { get; }
@@ -30,5 +36,7 @@ public DrumHit(DrumPad pad, double timeSeconds, int velocity = 127)
         public double TimeSeconds { get; }
 
         public int Velocity { get; }
+
+        public DrumArticulation Articulation { get; }
     }
 }
diff --git a/src/HitTheKit.Core/HitMatcher.cs b/src/HitTheKit.Core/HitMatcher.cs
index 55468b6..32cdef9 100644
--- a/src/HitTheKit.Core/HitMatcher.cs
+++ b/src/HitTheKit.Core/HitMatcher.cs
@@ -47,7 +47,8 @@ public bool TryMatch(
                         "The candidate list cannot contain null notes.",
                         nameof(notes));
 
-                if (_resolvedNotes.Contains(note) || note.Pad != hit.Pad)
+                if (_resolvedNotes.Contains(note) || note.Pad != hit.Pad ||
+                    note.Articulation != DrumArticulation.Default && note.Articulation != hit.Articulation)
                 {
                     continue;
                 }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Audio/DspSongClockPrototype.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Audio/DspSongClockPrototype.cs
index 3735fbd..9c6c4ed 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Audio/DspSongClockPrototype.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Audio/DspSongClockPrototype.cs
@@ -37,6 +37,7 @@ public sealed class DspSongClockPrototype : MonoBehaviour
         public double CountInSeconds => countInBeats * 60.0 / bpm;
         public string ExternalAudioPath => externalAudioPath;
         public double AudioPlaybackSpeed => audioPlaybackSpeed;
+        public bool IsPreviewing { get; private set; }
         public string LoadError { get; private set; }
 
         public void Configure(
@@ -153,8 +154,31 @@ public void RestartPlayback()
             completedLogged = false;
         }
 
+        public void PreviewFromSourceTime(double sourceTimeSeconds, double speed = 1.0)
+        {
+            if (generatedClip == null || audioSource == null)
+                throw new InvalidOperationException("Song audio is not loaded.");
+            if (double.IsNaN(sourceTimeSeconds) || double.IsInfinity(sourceTimeSeconds) ||
+                sourceTimeSeconds < 0 || sourceTimeSeconds >= generatedClip.length)
+                throw new ArgumentOutOfRangeException(nameof(sourceTimeSeconds));
+            if (double.IsNaN(speed) || double.IsInfinity(speed) || speed <= 0 || speed > 3)
+                throw new ArgumentOutOfRangeException(nameof(speed));
+            audioSource.Stop();
+            audioSource.pitch = (float)speed;
+            audioSource.time = (float)sourceTimeSeconds;
+            audioSource.Play();
+            IsPreviewing = true;
+        }
+
+        public void StopPreview()
+        {
+            if (audioSource != null) audioSource.Stop();
+            IsPreviewing = false;
+        }
+
         private void SchedulePlayback()
         {
+            IsPreviewing = false;
             audioSource.clip = generatedClip;
             audioSource.pitch = (float)audioPlaybackSpeed;
             var timeSource = new UnityDspTimeSource();
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartLoader.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartLoader.cs
index 44880b2..e95a9b7 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartLoader.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartLoader.cs
@@ -75,7 +75,17 @@ public LoadedChart Load(string json, string difficulty)
                 }
 
                 DrumPad pad = ParsePad(noteDto.pad, index);
-                notes.Add(new IndexedChartNote(new ChartNote(noteDto.time, pad), index));
+                int? velocity = noteDto.velocity == int.MinValue ? (int?)null : noteDto.velocity;
+                DrumArticulation articulation = ParseArticulation(noteDto.articulation, pad, index);
+                try
+                {
+                    notes.Add(new IndexedChartNote(
+                        new ChartNote(noteDto.time, pad, velocity, articulation), index));
+                }
+                catch (ArgumentException exception)
+                {
+                    throw new ChartLoadException($"Chart note at index {index} is invalid: {exception.Message}", exception);
+                }
             }
 
             notes.Sort((left, right) =>
@@ -161,6 +171,34 @@ private static DrumPad ParsePad(string pad, int index)
             }
         }
 
+        private static DrumArticulation ParseArticulation(string value, DrumPad pad, int index)
+        {
+            DrumArticulation articulation;
+            switch (value)
+            {
+                case null:
+                case "default": articulation = DrumArticulation.Default; break;
+                case "head": articulation = DrumArticulation.Head; break;
+                case "rim": articulation = DrumArticulation.Rim; break;
+                case "bow": articulation = DrumArticulation.Bow; break;
+                case "edge": articulation = DrumArticulation.Edge; break;
+                case "bell": articulation = DrumArticulation.Bell; break;
+                case "closed": articulation = DrumArticulation.Closed; break;
+                case "halfOpen": articulation = DrumArticulation.HalfOpen; break;
+                case "open": articulation = DrumArticulation.Open; break;
+                case "pedal": articulation = DrumArticulation.Pedal; break;
+                case "choke": articulation = DrumArticulation.Choke; break;
+                default:
+                    throw new ChartLoadException(
+                        $"Chart note at index {index} has unknown articulation '{value}'.");
+            }
+
+            if (!DrumArticulationValidator.IsValid(pad, articulation))
+                throw new ChartLoadException(
+                    $"Chart note at index {index} articulation '{value}' is invalid for pad '{pad}'.");
+            return articulation;
+        }
+
         private static bool IsFinite(double value)
         {
             return !double.IsNaN(value) && !double.IsInfinity(value);
@@ -190,6 +228,8 @@ private sealed class ChartNoteDto
         {
             public double time = double.NaN;
             public string pad;
+            public int velocity = int.MinValue;
+            public string articulation;
         }
     }
 }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartTimelinePrototype.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartTimelinePrototype.cs
index cbbc55b..f287acf 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartTimelinePrototype.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Charts/ChartTimelinePrototype.cs
@@ -67,7 +67,14 @@ public IReadOnlyList<ChartNote> CreateMatchingNotes()
             if (Timeline == null) throw new InvalidOperationException("The chart timeline has not started.");
             var result = new ChartNote[Timeline.Notes.Count];
             for (int index = 0; index < result.Length; index++)
-                result[index] = new ChartNote(Timeline.Notes[index].EffectiveTimeSeconds, Timeline.Notes[index].Note.Pad);
+            {
+                ChartNote note = Timeline.Notes[index].Note;
+                result[index] = new ChartNote(
+                    Timeline.Notes[index].EffectiveTimeSeconds,
+                    note.Pad,
+                    note.Velocity,
+                    note.Articulation);
+            }
             return Array.AsReadOnly(result);
         }
 
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Devices/MidiKitMappingEngine.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Devices/MidiKitMappingEngine.cs
index e4f544b..c9541d9 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Devices/MidiKitMappingEngine.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Devices/MidiKitMappingEngine.cs
@@ -232,8 +232,28 @@ public MvpDrumInputMappingStatus Map(
                 pad,
                 hit.Velocity,
                 hit.TimestampSeconds.Value,
-                DrumInputSource.Midi);
+                DrumInputSource.Midi,
+                ToDrumArticulation(hit.Articulation));
             return MvpDrumInputMappingStatus.Mapped;
         }
+
+        private static DrumArticulation ToDrumArticulation(KitArticulation articulation)
+        {
+            switch (articulation)
+            {
+                case KitArticulation.Default: return DrumArticulation.Default;
+                case KitArticulation.Head: return DrumArticulation.Head;
+                case KitArticulation.Rim: return DrumArticulation.Rim;
+                case KitArticulation.Bow: return DrumArticulation.Bow;
+                case KitArticulation.Edge: return DrumArticulation.Edge;
+                case KitArticulation.Bell: return DrumArticulation.Bell;
+                case KitArticulation.Closed: return DrumArticulation.Closed;
+                case KitArticulation.HalfOpen: return DrumArticulation.HalfOpen;
+                case KitArticulation.Open: return DrumArticulation.Open;
+                case KitArticulation.Pedal: return DrumArticulation.Pedal;
+                case KitArticulation.Choke: return DrumArticulation.Choke;
+                default: throw new ArgumentOutOfRangeException(nameof(articulation));
+            }
+        }
     }
 }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
index 15793de..1b5634f 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs
@@ -25,6 +25,7 @@ internal RecordedChartHit(DrumInputEvent input, int recordingIndex)
             Velocity = input.Velocity;
             TimeSeconds = input.SongTimeSeconds;
             Source = input.Source;
+            Articulation = input.Articulation;
             RecordingIndex = recordingIndex;
         }
 
@@ -32,6 +33,7 @@ internal RecordedChartHit(DrumInputEvent input, int recordingIndex)
         public int Velocity { get; }
         public double TimeSeconds { get; }
         public DrumInputSource Source { get; }
+        public DrumArticulation Articulation { get; }
         internal int RecordingIndex { get; }
     }
 
@@ -185,7 +187,12 @@ public static string Serialize(
                 RecordedChartHit hit = draft.Hits[index];
                 double time = Quantize(hit.TimeSeconds, bpm, quantization);
                 time = Math.Max(0, Math.Min(draft.DurationSeconds, time));
-                projected.Add(new ProjectedHit(time, hit.Pad, hit.RecordingIndex));
+                projected.Add(new ProjectedHit(
+                    time,
+                    hit.Pad,
+                    hit.Velocity,
+                    hit.Articulation,
+                    hit.RecordingIndex));
             }
             projected.Sort((left, right) =>
             {
@@ -205,7 +212,13 @@ public static string Serialize(
                     .Append(hit.TimeSeconds.ToString("0.#########", CultureInfo.InvariantCulture))
                     .Append(", \"pad\": \"")
                     .Append(PadId(hit.Pad))
-                    .Append("\" }");
+                    .Append("\", \"velocity\": ")
+                    .Append(hit.Velocity.ToString(CultureInfo.InvariantCulture));
+                if (hit.Articulation != DrumArticulation.Default)
+                    json.Append(", \"articulation\": \"")
+                        .Append(ArticulationId(hit.Articulation))
+                        .Append('"');
+                json.Append(" }");
             }
             if (projected.Count > 0) json.Append('\n').Append("    ");
             json.Append("]\n  }\n}\n");
@@ -245,18 +258,46 @@ private static string PadId(DrumPad pad)
             }
         }
 
+        private static string ArticulationId(DrumArticulation articulation)
+        {
+            switch (articulation)
+            {
+                case DrumArticulation.Default: return "default";
+                case DrumArticulation.Head: return "head";
+                case DrumArticulation.Rim: return "rim";
+                case DrumArticulation.Bow: return "bow";
+                case DrumArticulation.Edge: return "edge";
+                case DrumArticulation.Bell: return "bell";
+                case DrumArticulation.Closed: return "closed";
+                case DrumArticulation.HalfOpen: return "halfOpen";
+                case DrumArticulation.Open: return "open";
+                case DrumArticulation.Pedal: return "pedal";
+                case DrumArticulation.Choke: return "choke";
+                default: throw new ArgumentOutOfRangeException(nameof(articulation));
+            }
+        }
+
         private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
 
         private sealed class ProjectedHit
         {
-            public ProjectedHit(double timeSeconds, DrumPad pad, int recordingIndex)
+            public ProjectedHit(
+                double timeSeconds,
+                DrumPad pad,
+                int velocity,
+                DrumArticulation articulation,
+                int recordingIndex)
             {
                 TimeSeconds = timeSeconds;
                 Pad = pad;
+                Velocity = velocity;
+                Articulation = articulation;
                 RecordingIndex = recordingIndex;
             }
             public double TimeSeconds { get; }
             public DrumPad Pad { get; }
+            public int Velocity { get; }
+            public DrumArticulation Articulation { get; }
             public int RecordingIndex { get; }
         }
     }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs
index 80954a2..6634fe6 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartDraftEditor.cs
@@ -12,19 +12,22 @@ internal EditableChartNote(
             int identity,
             DrumPad pad,
             int velocity,
+            DrumArticulation articulation,
             double timeSeconds,
             DrumInputSource source)
         {
             Identity = identity;
             Pad = pad;
             Velocity = velocity;
+            Articulation = articulation;
             TimeSeconds = timeSeconds;
             Source = source;
         }
 
         public int Identity { get; }
         public DrumPad Pad { get; internal set; }
-        public int Velocity { get; }
+        public int Velocity { get; internal set; }
+        public DrumArticulation Articulation { get; internal set; }
         public double TimeSeconds { get; internal set; }
         public DrumInputSource Source { get; }
     }
@@ -44,7 +47,8 @@ public ChartDraftEditor(ChartRecordingDraft draft)
             for (int index = 0; index < draft.Hits.Count; index++)
             {
                 RecordedChartHit hit = draft.Hits[index];
-                notes.Add(new EditableChartNote(nextIdentity++, hit.Pad, hit.Velocity, hit.TimeSeconds, hit.Source));
+                notes.Add(new EditableChartNote(
+                    nextIdentity++, hit.Pad, hit.Velocity, hit.Articulation, hit.TimeSeconds, hit.Source));
             }
             Sort();
             readOnlyNotes = notes.AsReadOnly();
@@ -54,24 +58,48 @@ public ChartDraftEditor(ChartRecordingDraft draft)
         public IReadOnlyList<EditableChartNote> Notes => readOnlyNotes;
 
         public int Update(int index, double timeSeconds, DrumPad pad)
+        {
+            EditableChartNote note = At(index);
+            DrumArticulation articulation = DrumArticulationValidator.IsValid(pad, note.Articulation)
+                ? note.Articulation
+                : DrumArticulation.Default;
+            return Update(index, timeSeconds, pad, note.Velocity, articulation);
+        }
+
+        public int Update(
+            int index,
+            double timeSeconds,
+            DrumPad pad,
+            int velocity,
+            DrumArticulation articulation)
         {
             EditableChartNote note = At(index);
             ValidateTime(timeSeconds);
             ValidatePad(pad);
+            ValidateVelocity(velocity);
+            DrumArticulationValidator.EnsureValid(pad, articulation);
             note.TimeSeconds = timeSeconds;
             note.Pad = pad;
+            note.Velocity = velocity;
+            note.Articulation = articulation;
             Sort();
             return notes.IndexOf(note);
         }
 
-        public int Add(double timeSeconds, DrumPad pad, int velocity = 100)
+        public int Add(
+            double timeSeconds,
+            DrumPad pad,
+            int velocity = 100,
+            DrumArticulation articulation = DrumArticulation.Default)
         {
             ValidateTime(timeSeconds);
             ValidatePad(pad);
-            if (velocity < 0 || velocity > 127) throw new ArgumentOutOfRangeException(nameof(velocity));
+            ValidateVelocity(velocity);
+            DrumArticulationValidator.EnsureValid(pad, articulation);
             if (notes.Count >= ChartRecordingSession.MaximumHits)
                 throw new InvalidOperationException($"A chart cannot exceed {ChartRecordingSession.MaximumHits} notes.");
-            var note = new EditableChartNote(nextIdentity++, pad, velocity, timeSeconds, DrumInputSource.Test);
+            var note = new EditableChartNote(
+                nextIdentity++, pad, velocity, articulation, timeSeconds, DrumInputSource.Test);
             notes.Add(note);
             Sort();
             return notes.IndexOf(note);
@@ -86,7 +114,12 @@ public ChartRecordingDraft BuildDraft()
             {
                 EditableChartNote note = notes[index];
                 hits[index] = new RecordedChartHit(
-                    new DrumInputEvent(note.Pad, note.Velocity, note.TimeSeconds, note.Source),
+                    new DrumInputEvent(
+                        note.Pad,
+                        note.Velocity,
+                        note.TimeSeconds,
+                        note.Source,
+                        note.Articulation),
                     index);
             }
             return new ChartRecordingDraft(durationSeconds, hits);
@@ -111,6 +144,11 @@ private static void ValidatePad(DrumPad pad)
             if (!Enum.IsDefined(typeof(DrumPad), pad)) throw new ArgumentOutOfRangeException(nameof(pad));
         }
 
+        private static void ValidateVelocity(int velocity)
+        {
+            if (velocity < 1 || velocity > 127) throw new ArgumentOutOfRangeException(nameof(velocity));
+        }
+
         private void Sort() => notes.Sort((left, right) =>
         {
             int byTime = left.TimeSeconds.CompareTo(right.TimeSeconds);
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs
new file mode 100644
index 0000000..849bd1f
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs
@@ -0,0 +1,257 @@
+using System;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace HitTheKit.Unity.Gameplay
+{
+    public sealed class ChartWaveformModel
+    {
+        private readonly float[] peaks;
+
+        public ChartWaveformModel(float[] sourcePeaks, double durationSeconds)
+        {
+            if (sourcePeaks == null || sourcePeaks.Length < 2)
+                throw new ArgumentException("A waveform requires at least two peak values.", nameof(sourcePeaks));
+            if (!IsFinite(durationSeconds) || durationSeconds <= 0)
+                throw new ArgumentOutOfRangeException(nameof(durationSeconds));
+            peaks = new float[sourcePeaks.Length];
+            for (int index = 0; index < peaks.Length; index++)
+            {
+                float value = sourcePeaks[index];
+                if (float.IsNaN(value) || float.IsInfinity(value))
+                    throw new ArgumentException("Waveform peaks must be finite.", nameof(sourcePeaks));
+                peaks[index] = Mathf.Clamp01(Mathf.Abs(value));
+            }
+            DurationSeconds = durationSeconds;
+            ResetZoom();
+        }
+
+        public double DurationSeconds { get; }
+        public double ViewStartSeconds { get; private set; }
+        public double ViewEndSeconds { get; private set; }
+        public double SelectedTimeSeconds { get; private set; }
+        public int PeakCount => peaks.Length;
+        public float PeakAt(int index) => peaks[index];
+
+        public double Scrub(double normalizedPosition)
+        {
+            if (!IsFinite(normalizedPosition)) throw new ArgumentOutOfRangeException(nameof(normalizedPosition));
+            double clamped = Math.Max(0, Math.Min(1, normalizedPosition));
+            SelectedTimeSeconds = ViewStartSeconds + (ViewEndSeconds - ViewStartSeconds) * clamped;
+            return SelectedTimeSeconds;
+        }
+
+        public void Select(double timeSeconds)
+        {
+            if (!IsFinite(timeSeconds)) throw new ArgumentOutOfRangeException(nameof(timeSeconds));
+            SelectedTimeSeconds = Math.Max(0, Math.Min(DurationSeconds, timeSeconds));
+        }
+
+        public void Zoom(double factor)
+        {
+            if (!IsFinite(factor) || factor <= 0) throw new ArgumentOutOfRangeException(nameof(factor));
+            double current = ViewEndSeconds - ViewStartSeconds;
+            double minimum = Math.Min(DurationSeconds, 0.5);
+            double next = Math.Max(minimum, Math.Min(DurationSeconds, current / factor));
+            double anchor = SelectedTimeSeconds;
+            double ratio = current > 0 ? (anchor - ViewStartSeconds) / current : 0.5;
+            double start = anchor - next * ratio;
+            start = Math.Max(0, Math.Min(DurationSeconds - next, start));
+            ViewStartSeconds = start;
+            ViewEndSeconds = start + next;
+        }
+
+        public void ResetZoom()
+        {
+            ViewStartSeconds = 0;
+            ViewEndSeconds = DurationSeconds;
+            SelectedTimeSeconds = Math.Max(0, Math.Min(DurationSeconds, SelectedTimeSeconds));
+        }
+
+        public static ChartWaveformModel FromInterleaved(
+            float[] samples,
+            int channels,
+            double durationSeconds,
+            int pointCount = 512)
+        {
+            if (samples == null || samples.Length == 0) throw new ArgumentException("Samples are required.", nameof(samples));
+            if (channels <= 0 || samples.Length % channels != 0) throw new ArgumentOutOfRangeException(nameof(channels));
+            if (pointCount < 2 || pointCount > 4096) throw new ArgumentOutOfRangeException(nameof(pointCount));
+            var result = new float[pointCount];
+            int frames = samples.Length / channels;
+            for (int point = 0; point < pointCount; point++)
+            {
+                int startFrame = (int)((long)point * frames / pointCount);
+                int endFrame = Math.Max(startFrame + 1, (int)((long)(point + 1) * frames / pointCount));
+                endFrame = Math.Min(frames, endFrame);
+                float peak = 0;
+                for (int frame = startFrame; frame < endFrame; frame++)
+                    for (int channel = 0; channel < channels; channel++)
+                        peak = Math.Max(peak, Math.Abs(samples[frame * channels + channel]));
+                result[point] = peak;
+            }
+            return new ChartWaveformModel(result, durationSeconds);
+        }
+
+        public static ChartWaveformModel FromAudioClip(
+            AudioClip clip,
+            int pointCount = 512,
+            int framesPerRead = 4096)
+        {
+            if (clip == null) throw new ArgumentNullException(nameof(clip));
+            if (clip.samples <= 0 || clip.channels <= 0 || clip.length <= 0)
+                throw new ArgumentException("Audio clip is empty.", nameof(clip));
+            if (pointCount < 2 || pointCount > 4096) throw new ArgumentOutOfRangeException(nameof(pointCount));
+            if (framesPerRead <= 0 || framesPerRead > 32768)
+                throw new ArgumentOutOfRangeException(nameof(framesPerRead));
+
+            int boundedRead = Math.Min(framesPerRead, clip.samples);
+            var buffer = new float[boundedRead * clip.channels];
+            var result = new float[pointCount];
+            for (int point = 0; point < pointCount; point++)
+            {
+                int startFrame = (int)((long)point * clip.samples / pointCount);
+                int endFrame = Math.Max(startFrame + 1, (int)((long)(point + 1) * clip.samples / pointCount));
+                endFrame = Math.Min(clip.samples, endFrame);
+                float peak = 0;
+                for (int offset = startFrame; offset < endFrame; offset += boundedRead)
+                {
+                    int frames = Math.Min(boundedRead, endFrame - offset);
+                    if (!clip.GetData(buffer, offset))
+                        throw new InvalidOperationException("Audio samples could not be read.");
+                    int sampleCount = frames * clip.channels;
+                    for (int index = 0; index < sampleCount; index++)
+                        peak = Math.Max(peak, Math.Abs(buffer[index]));
+                }
+                result[point] = peak;
+            }
+            return new ChartWaveformModel(result, clip.length);
+        }
+
+        private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+    }
+
+    public sealed class ChartWaveformView : VisualElement
+    {
+        private bool dragging;
+        private ChartWaveformModel model;
+
+        public ChartWaveformView()
+        {
+            focusable = true;
+            generateVisualContent += Draw;
+            RegisterCallback<PointerDownEvent>(OnPointerDown);
+            RegisterCallback<PointerMoveEvent>(OnPointerMove);
+            RegisterCallback<PointerUpEvent>(OnPointerUp);
+            RegisterCallback<PointerCaptureOutEvent>(_ => dragging = false);
+        }
+
+        public event Action<double> Scrubbed;
+        public ChartWaveformModel Model => model;
+
+        public void SetModel(ChartWaveformModel value)
+        {
+            model = value;
+            MarkDirtyRepaint();
+        }
+
+        public void SetSelectedTime(double value)
+        {
+            model?.Select(value);
+            MarkDirtyRepaint();
+        }
+
+        public void Zoom(double factor)
+        {
+            model?.Zoom(factor);
+            MarkDirtyRepaint();
+        }
+
+        public void ResetZoom()
+        {
+            model?.ResetZoom();
+            MarkDirtyRepaint();
+        }
+
+        private void OnPointerDown(PointerDownEvent evt)
+        {
+            if (evt.button != 0 || model == null) return;
+            dragging = true;
+            this.CapturePointer(evt.pointerId);
+            Scrub(evt.localPosition.x);
+            evt.StopPropagation();
+        }
+
+        private void OnPointerMove(PointerMoveEvent evt)
+        {
+            if (!dragging || model == null) return;
+            Scrub(evt.localPosition.x);
+            evt.StopPropagation();
+        }
+
+        private void OnPointerUp(PointerUpEvent evt)
+        {
+            dragging = false;
+            if (this.HasPointerCapture(evt.pointerId)) this.ReleasePointer(evt.pointerId);
+        }
+
+        private void Scrub(float x)
+        {
+            double width = Math.Max(1, contentRect.width);
+            double selected = model.Scrub(x / width);
+            MarkDirtyRepaint();
+            Scrubbed?.Invoke(selected);
+        }
+
+        private void Draw(MeshGenerationContext context)
+        {
+            Painter2D painter = context.painter2D;
+            Rect rect = contentRect;
+            painter.fillColor = new Color(0.01f, 0.04f, 0.075f, 0.98f);
+            painter.BeginPath();
+            painter.MoveTo(new Vector2(0, 0));
+            painter.LineTo(new Vector2(rect.width, 0));
+            painter.LineTo(new Vector2(rect.width, rect.height));
+            painter.LineTo(new Vector2(0, rect.height));
+            painter.ClosePath();
+            painter.Fill();
+            if (model == null || rect.width <= 1 || rect.height <= 1) return;
+
+            float center = rect.height * 0.5f;
+            painter.strokeColor = new Color(0.22f, 0.55f, 0.68f, 0.45f);
+            painter.lineWidth = 1;
+            painter.BeginPath();
+            painter.MoveTo(new Vector2(0, center));
+            painter.LineTo(new Vector2(rect.width, center));
+            painter.Stroke();
+
+            double viewDuration = model.ViewEndSeconds - model.ViewStartSeconds;
+            int first = Math.Max(0, (int)Math.Floor(model.ViewStartSeconds / model.DurationSeconds * (model.PeakCount - 1)));
+            int last = Math.Min(model.PeakCount - 1, (int)Math.Ceiling(model.ViewEndSeconds / model.DurationSeconds * (model.PeakCount - 1)));
+            painter.strokeColor = new Color(0.24f, 0.86f, 1f, 0.9f);
+            painter.lineWidth = Math.Max(1, rect.width / Math.Max(1, last - first + 1));
+            for (int index = first; index <= last; index++)
+            {
+                double time = index / (double)(model.PeakCount - 1) * model.DurationSeconds;
+                float x = (float)((time - model.ViewStartSeconds) / viewDuration * rect.width);
+                float amplitude = model.PeakAt(index) * (rect.height * 0.42f);
+                painter.BeginPath();
+                painter.MoveTo(new Vector2(x, center - amplitude));
+                painter.LineTo(new Vector2(x, center + amplitude));
+                painter.Stroke();
+            }
+
+            if (model.SelectedTimeSeconds >= model.ViewStartSeconds &&
+                model.SelectedTimeSeconds <= model.ViewEndSeconds)
+            {
+                float x = (float)((model.SelectedTimeSeconds - model.ViewStartSeconds) / viewDuration * rect.width);
+                painter.strokeColor = new Color(1f, 0.67f, 0.18f, 1f);
+                painter.lineWidth = 2.5f;
+                painter.BeginPath();
+                painter.MoveTo(new Vector2(x, 0));
+                painter.LineTo(new Vector2(x, rect.height));
+                painter.Stroke();
+            }
+        }
+    }
+}
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs.meta b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs.meta
new file mode 100644
index 0000000..d4d7a02
--- /dev/null
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartWaveform.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 3b0d8b53ae8a42c2bfc569bf322e7f35
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
index 92c69c2..46d353f 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs
@@ -88,10 +88,21 @@ public sealed class GameplayHighwayController : MonoBehaviour
         private Label chartNoteSelectionLabel;
         private TextField chartNoteTimeField;
         private DropdownField chartNotePadField;
+        private TextField chartNoteVelocityField;
+        private DropdownField chartNoteArticulationField;
         private Button chartNoteAddButton;
         private Button chartNoteApplyButton;
         private Button chartNoteDeleteButton;
         private Label chartNoteStatusLabel;
+        private VisualElement chartWaveformHost;
+        private ChartWaveformView chartWaveformView;
+        private Label chartWaveformTimeLabel;
+        private Button chartWaveformZoomInButton;
+        private Button chartWaveformZoomOutButton;
+        private Button chartWaveformResetButton;
+        private Button chartWaveformPreviewButton;
+        private Button chartWaveformStopButton;
+        private readonly List<DrumArticulation> chartArticulationChoices = new List<DrumArticulation>();
         private GameplayHighwaySurface surface;
         private GameplayKitSurface kitSurface;
         private bool showInstructionalKit;
@@ -190,6 +201,7 @@ private void OnDisable()
         private void OnDestroy()
         {
             FlushPracticeTime();
+            songClock?.StopPreview();
             ReleaseAudioFeedback();
         }
 
@@ -300,11 +312,21 @@ private void BindView()
             chartNoteSelectionLabel = root.Q<Label>("chart-note-selection");
             chartNoteTimeField = root.Q<TextField>("chart-note-time");
             chartNotePadField = root.Q<DropdownField>("chart-note-pad");
+            chartNoteVelocityField = root.Q<TextField>("chart-note-velocity");
+            chartNoteArticulationField = root.Q<DropdownField>("chart-note-articulation");
             chartNoteAddButton = root.Q<Button>("chart-note-add");
             chartNoteApplyButton = root.Q<Button>("chart-note-apply");
             chartNoteDeleteButton = root.Q<Button>("chart-note-delete");
             chartNoteStatusLabel = root.Q<Label>("chart-note-status");
+            chartWaveformHost = root.Q<VisualElement>("chart-waveform-host");
+            chartWaveformTimeLabel = root.Q<Label>("chart-waveform-time");
+            chartWaveformZoomInButton = root.Q<Button>("chart-waveform-zoom-in");
+            chartWaveformZoomOutButton = root.Q<Button>("chart-waveform-zoom-out");
+            chartWaveformResetButton = root.Q<Button>("chart-waveform-reset");
+            chartWaveformPreviewButton = root.Q<Button>("chart-waveform-preview");
+            chartWaveformStopButton = root.Q<Button>("chart-waveform-stop");
             ConfigureChartNoteEditorView();
+            ConfigureChartWaveformView();
             PlayerPreferencesSnapshot preferences = PlayerPreferencesRuntime.Current.Snapshot;
             root.EnableInClassList("gameplay--high-contrast", preferences.HighContrast);
             root.EnableInClassList("gameplay--reduced-motion", preferences.ReducedMotion);
@@ -535,6 +557,7 @@ public void TogglePause()
         public void RestartRun()
         {
             FlushPracticeTime();
+            songClock?.StopPreview();
             practiceTimer.ResetAttempt();
             resultRecorded = false;
             chartDraft = null;
@@ -614,6 +637,7 @@ private void ShowResults(HitMatchingSnapshot matchingSnapshot)
                 chartSaveRawButton?.SetEnabled(hitCount > 0);
                 chartSaveEighthButton?.SetEnabled(hitCount > 0);
                 chartSaveSixteenthButton?.SetEnabled(hitCount > 0);
+                ConfigureChartWaveform();
                 RefreshChartNoteEditor(hitCount > 0 ? 0 : -1);
                 SetDisplayed(chartCreatorResults, true);
             }
@@ -706,6 +730,19 @@ public int EditChartNote(int index, double timeSeconds, DrumPad pad)
             return selected;
         }
 
+        public int EditChartNote(
+            int index,
+            double timeSeconds,
+            DrumPad pad,
+            int velocity,
+            DrumArticulation articulation)
+        {
+            if (chartDraftEditor == null) throw new InvalidOperationException("Finish a Chart Creator take first.");
+            int selected = chartDraftEditor.Update(index, timeSeconds, pad, velocity, articulation);
+            RefreshChartNoteEditor(selected);
+            return selected;
+        }
+
         public int AddChartNote(double timeSeconds, DrumPad pad)
         {
             if (chartDraftEditor == null) throw new InvalidOperationException("Finish a Chart Creator take first.");
@@ -714,6 +751,18 @@ public int AddChartNote(double timeSeconds, DrumPad pad)
             return selected;
         }
 
+        public int AddChartNote(
+            double timeSeconds,
+            DrumPad pad,
+            int velocity,
+            DrumArticulation articulation)
+        {
+            if (chartDraftEditor == null) throw new InvalidOperationException("Finish a Chart Creator take first.");
+            int selected = chartDraftEditor.Add(timeSeconds, pad, velocity, articulation);
+            RefreshChartNoteEditor(selected);
+            return selected;
+        }
+
         public void DeleteChartNote(int index)
         {
             if (chartDraftEditor == null) throw new InvalidOperationException("Finish a Chart Creator take first.");
@@ -832,6 +881,11 @@ private void BindRunControls()
             if (chartNoteAddButton != null) chartNoteAddButton.clicked += AddChartNoteFromView;
             if (chartNoteApplyButton != null) chartNoteApplyButton.clicked += ApplyChartNoteFromView;
             if (chartNoteDeleteButton != null) chartNoteDeleteButton.clicked += DeleteChartNoteFromView;
+            if (chartWaveformZoomInButton != null) chartWaveformZoomInButton.clicked += ZoomChartWaveformIn;
+            if (chartWaveformZoomOutButton != null) chartWaveformZoomOutButton.clicked += ZoomChartWaveformOut;
+            if (chartWaveformResetButton != null) chartWaveformResetButton.clicked += ResetChartWaveform;
+            if (chartWaveformPreviewButton != null) chartWaveformPreviewButton.clicked += PreviewChartWaveform;
+            if (chartWaveformStopButton != null) chartWaveformStopButton.clicked += StopChartWaveformPreview;
         }
 
         private void UnbindRunControls()
@@ -848,15 +902,23 @@ private void UnbindRunControls()
             if (chartNoteAddButton != null) chartNoteAddButton.clicked -= AddChartNoteFromView;
             if (chartNoteApplyButton != null) chartNoteApplyButton.clicked -= ApplyChartNoteFromView;
             if (chartNoteDeleteButton != null) chartNoteDeleteButton.clicked -= DeleteChartNoteFromView;
+            if (chartWaveformZoomInButton != null) chartWaveformZoomInButton.clicked -= ZoomChartWaveformIn;
+            if (chartWaveformZoomOutButton != null) chartWaveformZoomOutButton.clicked -= ZoomChartWaveformOut;
+            if (chartWaveformResetButton != null) chartWaveformResetButton.clicked -= ResetChartWaveform;
+            if (chartWaveformPreviewButton != null) chartWaveformPreviewButton.clicked -= PreviewChartWaveform;
+            if (chartWaveformStopButton != null) chartWaveformStopButton.clicked -= StopChartWaveformPreview;
         }
 
         private void ConfigureChartNoteEditorView()
         {
-            if (chartNoteList == null || chartNotePadField == null) return;
+            if (chartNoteList == null || chartNotePadField == null || chartNoteArticulationField == null) return;
             chartNotePadField.choices = new List<string>();
             foreach (DrumPad pad in Enum.GetValues(typeof(DrumPad)))
                 chartNotePadField.choices.Add(GameplayHighwayLanes.Find(pad).Label);
             chartNotePadField.index = 0;
+            chartNotePadField.UnregisterValueChangedCallback(HandleChartNotePadChanged);
+            chartNotePadField.RegisterValueChangedCallback(HandleChartNotePadChanged);
+            RefreshChartArticulationChoices(DrumPad.Kick, DrumArticulation.Default);
             chartNoteList.fixedItemHeight = 30;
             chartNoteList.virtualizationMethod = CollectionVirtualizationMethod.FixedHeight;
             chartNoteList.selectionType = SelectionType.Single;
@@ -875,7 +937,10 @@ private void ConfigureChartNoteEditorView()
                     return;
                 }
                 EditableChartNote note = chartDraftEditor.Notes[index];
-                label.text = $"{index + 1:000}   {note.TimeSeconds:0.000}s   {GameplayHighwayLanes.Find(note.Pad).Label}";
+                string articulation = note.Articulation == DrumArticulation.Default
+                    ? string.Empty
+                    : $" · {ArticulationLabel(note.Articulation)}";
+                label.text = $"{index + 1:000}   {note.TimeSeconds:0.000}s   {GameplayHighwayLanes.Find(note.Pad).Label}{articulation} · V{note.Velocity}";
             };
             chartNoteList.selectionChanged -= HandleChartNoteSelectionChanged;
             chartNoteList.selectionChanged += HandleChartNoteSelectionChanged;
@@ -916,12 +981,17 @@ private void RenderSelectedChartNote()
             {
                 if (chartNoteSelectionLabel != null) chartNoteSelectionLabel.text = "SELEZIONA UNA NOTA";
                 if (chartNoteTimeField != null) chartNoteTimeField.value = string.Empty;
+                if (chartNoteVelocityField != null) chartNoteVelocityField.value = string.Empty;
                 return;
             }
             EditableChartNote note = chartDraftEditor.Notes[index];
             chartNoteSelectionLabel.text = $"NOTA {index + 1:000} · VELOCITY {note.Velocity}";
             chartNoteTimeField.value = note.TimeSeconds.ToString("0.000", CultureInfo.InvariantCulture);
             chartNotePadField.index = (int)note.Pad;
+            chartNoteVelocityField.value = note.Velocity.ToString(CultureInfo.InvariantCulture);
+            RefreshChartArticulationChoices(note.Pad, note.Articulation);
+            chartWaveformView?.SetSelectedTime(note.TimeSeconds);
+            RefreshChartWaveformTime();
         }
 
         private void ApplyChartNoteFromView()
@@ -929,7 +999,12 @@ private void ApplyChartNoteFromView()
             try
             {
                 int index = chartNoteList?.selectedIndex ?? -1;
-                int selected = EditChartNote(index, ParseChartNoteTime(), SelectedChartNotePad());
+                int selected = EditChartNote(
+                    index,
+                    ParseChartNoteTime(),
+                    SelectedChartNotePad(),
+                    ParseChartNoteVelocity(),
+                    SelectedChartNoteArticulation());
                 chartNoteStatusLabel.text = $"NOTA {selected + 1:000} AGGIORNATA";
             }
             catch (Exception exception) { SetChartNoteError(exception); }
@@ -939,7 +1014,11 @@ private void AddChartNoteFromView()
         {
             try
             {
-                int selected = AddChartNote(ParseChartNoteTime(), SelectedChartNotePad());
+                int selected = AddChartNote(
+                    ParseChartNoteTime(),
+                    SelectedChartNotePad(),
+                    ParseChartNoteVelocity(),
+                    SelectedChartNoteArticulation());
                 chartNoteStatusLabel.text = $"NOTA {selected + 1:000} AGGIUNTA";
             }
             catch (Exception exception) { SetChartNoteError(exception); }
@@ -972,6 +1051,152 @@ private DrumPad SelectedChartNotePad()
             return (DrumPad)index;
         }
 
+        private int ParseChartNoteVelocity()
+        {
+            if (int.TryParse(chartNoteVelocityField?.value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int velocity) &&
+                velocity >= 1 && velocity <= 127)
+                return velocity;
+            throw new InvalidOperationException("Inserisci una velocity valida fra 1 e 127.");
+        }
+
+        private DrumArticulation SelectedChartNoteArticulation()
+        {
+            int index = chartNoteArticulationField?.index ?? -1;
+            if (index < 0 || index >= chartArticulationChoices.Count)
+                throw new InvalidOperationException("Seleziona un'articolazione valida.");
+            return chartArticulationChoices[index];
+        }
+
+        private void HandleChartNotePadChanged(ChangeEvent<string> _)
+        {
+            DrumPad pad = SelectedChartNotePad();
+            RefreshChartArticulationChoices(pad, DrumArticulation.Default);
+        }
+
+        private void RefreshChartArticulationChoices(DrumPad pad, DrumArticulation selected)
+        {
+            chartArticulationChoices.Clear();
+            var labels = new List<string>();
+            foreach (DrumArticulation articulation in Enum.GetValues(typeof(DrumArticulation)))
+            {
+                if (!DrumArticulationValidator.IsValid(pad, articulation)) continue;
+                chartArticulationChoices.Add(articulation);
+                labels.Add(ArticulationLabel(articulation));
+            }
+            chartNoteArticulationField.choices = labels;
+            int index = chartArticulationChoices.IndexOf(selected);
+            chartNoteArticulationField.index = index >= 0 ? index : 0;
+        }
+
+        private static string ArticulationLabel(DrumArticulation articulation)
+        {
+            switch (articulation)
+            {
+                case DrumArticulation.Default: return "STANDARD / QUALSIASI";
+                case DrumArticulation.Head: return "PELLE / CENTRO";
+                case DrumArticulation.Rim: return "BORDO / RIM";
+                case DrumArticulation.Bow: return "CORPO / BOW";
+                case DrumArticulation.Edge: return "BORDO / EDGE";
+                case DrumArticulation.Bell: return "CAMPANA / BELL";
+                case DrumArticulation.Closed: return "CHIUSO";
+                case DrumArticulation.HalfOpen: return "SEMIAPERTO";
+                case DrumArticulation.Open: return "APERTO";
+                case DrumArticulation.Pedal: return "PEDALE";
+                case DrumArticulation.Choke: return "STOP / CHOKE";
+                default: throw new ArgumentOutOfRangeException(nameof(articulation));
+            }
+        }
+
+        private void ConfigureChartWaveformView()
+        {
+            if (chartWaveformHost == null) return;
+            if (chartWaveformView != null) chartWaveformView.Scrubbed -= HandleChartWaveformScrubbed;
+            chartWaveformHost.Clear();
+            chartWaveformView = new ChartWaveformView { name = "chart-waveform" };
+            chartWaveformView.style.flexGrow = 1;
+            chartWaveformView.Scrubbed += HandleChartWaveformScrubbed;
+            chartWaveformHost.Add(chartWaveformView);
+        }
+
+        private void ConfigureChartWaveform()
+        {
+            if (chartWaveformView == null) return;
+            AudioClip clip = songClock?.GeneratedClip;
+            if (clip == null)
+            {
+                chartWaveformView.SetModel(null);
+                chartWaveformPreviewButton?.SetEnabled(false);
+                if (chartWaveformTimeLabel != null) chartWaveformTimeLabel.text = "WAVEFORM NON DISPONIBILE";
+                return;
+            }
+
+            try
+            {
+                chartWaveformView.SetModel(ChartWaveformModel.FromAudioClip(clip));
+                chartWaveformPreviewButton?.SetEnabled(true);
+                RefreshChartWaveformTime();
+            }
+            catch (Exception exception)
+            {
+                chartWaveformView.SetModel(null);
+                chartWaveformPreviewButton?.SetEnabled(false);
+                if (chartWaveformTimeLabel != null) chartWaveformTimeLabel.text = "WAVEFORM NON LEGGIBILE";
+                if (chartNoteStatusLabel != null) chartNoteStatusLabel.text = exception.Message;
+            }
+        }
+
+        private void HandleChartWaveformScrubbed(double timeSeconds)
+        {
+            if (chartNoteTimeField != null)
+                chartNoteTimeField.value = timeSeconds.ToString("0.000", CultureInfo.InvariantCulture);
+            RefreshChartWaveformTime();
+        }
+
+        private void RefreshChartWaveformTime()
+        {
+            ChartWaveformModel model = chartWaveformView?.Model;
+            if (chartWaveformTimeLabel == null || model == null) return;
+            chartWaveformTimeLabel.text =
+                $"PLAYHEAD {model.SelectedTimeSeconds:0.000}s · VISTA {model.ViewStartSeconds:0.00}–{model.ViewEndSeconds:0.00}s";
+        }
+
+        private void ZoomChartWaveformIn()
+        {
+            chartWaveformView?.Zoom(2.0);
+            RefreshChartWaveformTime();
+        }
+
+        private void ZoomChartWaveformOut()
+        {
+            chartWaveformView?.Zoom(0.5);
+            RefreshChartWaveformTime();
+        }
+
+        private void ResetChartWaveform()
+        {
+            chartWaveformView?.ResetZoom();
+            RefreshChartWaveformTime();
+        }
+
+        private void PreviewChartWaveform()
+        {
+            try
+            {
+                ChartWaveformModel model = chartWaveformView?.Model ??
+                    throw new InvalidOperationException("Waveform non disponibile.");
+                double sourceTime = Math.Min(model.SelectedTimeSeconds, Math.Max(0, model.DurationSeconds - 0.001));
+                songClock.PreviewFromSourceTime(sourceTime, CurrentSession.SpeedMultiplier);
+                if (chartNoteStatusLabel != null) chartNoteStatusLabel.text = $"ANTEPRIMA DA {sourceTime:0.000}s";
+            }
+            catch (Exception exception) { SetChartNoteError(exception); }
+        }
+
+        private void StopChartWaveformPreview()
+        {
+            songClock?.StopPreview();
+            if (chartNoteStatusLabel != null) chartNoteStatusLabel.text = "ANTEPRIMA FERMA";
+        }
+
         private void SetChartNoteError(Exception exception)
         {
             if (chartNoteStatusLabel != null) chartNoteStatusLabel.text = "MODIFICA NON RIUSCITA · " + exception.Message;
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayKitVisualModel.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayKitVisualModel.cs
index 87d0b62..4f9a36f 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayKitVisualModel.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayKitVisualModel.cs
@@ -87,6 +87,26 @@ public static GameplayKitZone DefaultFor(DrumPad pad)
             }
         }
 
+        public static GameplayKitZone For(DrumPad pad, DrumArticulation articulation)
+        {
+            DrumArticulationValidator.EnsureValid(pad, articulation);
+            switch (articulation)
+            {
+                case DrumArticulation.Default: return DefaultFor(pad);
+                case DrumArticulation.Head: return GameplayKitZone.Head;
+                case DrumArticulation.Rim: return GameplayKitZone.Rim;
+                case DrumArticulation.Bell: return GameplayKitZone.Bell;
+                case DrumArticulation.Pedal: return GameplayKitZone.Pedal;
+                case DrumArticulation.Edge:
+                case DrumArticulation.Choke: return GameplayKitZone.Edge;
+                case DrumArticulation.Bow:
+                case DrumArticulation.Closed:
+                case DrumArticulation.HalfOpen:
+                case DrumArticulation.Open: return GameplayKitZone.Bow;
+                default: throw new ArgumentOutOfRangeException(nameof(articulation));
+            }
+        }
+
         public static string BeginnerInstruction(DrumPad pad)
         {
             switch (pad)
@@ -139,6 +159,7 @@ public GameplayKitTargetState Calculate(
                 throw new ArgumentOutOfRangeException(nameof(pulseIntensity));
 
             double nearest = double.PositiveInfinity;
+            DrumArticulation nearestArticulation = DrumArticulation.Default;
             if (upcomingNotes != null)
             {
                 for (int index = 0; index < upcomingNotes.Count; index++)
@@ -148,6 +169,7 @@ public GameplayKitTargetState Calculate(
                     double delta = note.EffectiveTimeSeconds - songPositionSeconds;
                     if (delta < 0 || delta > preparationSeconds || delta >= nearest) continue;
                     nearest = delta;
+                    nearestArticulation = note.Note.Articulation;
                 }
             }
 
@@ -160,7 +182,7 @@ public GameplayKitTargetState Calculate(
 
             return new GameplayKitTargetState(
                 pad,
-                GameplayKitZoneResolver.DefaultFor(pad),
+                GameplayKitZoneResolver.For(pad, nearestArticulation),
                 isUpcoming,
                 isUpcoming ? nearest : double.PositiveInfinity,
                 intensity,
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Input/DrumInputEvent.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Input/DrumInputEvent.cs
index 5acf741..72974fd 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Input/DrumInputEvent.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Input/DrumInputEvent.cs
@@ -16,7 +16,8 @@ public DrumInputEvent(
             DrumPad pad,
             int velocity,
             double songTimeSeconds,
-            DrumInputSource source = DrumInputSource.Keyboard)
+            DrumInputSource source = DrumInputSource.Keyboard,
+            DrumArticulation articulation = DrumArticulation.Default)
         {
             if (!Enum.IsDefined(typeof(DrumPad), pad))
             {
@@ -38,18 +39,22 @@ public DrumInputEvent(
                 throw new ArgumentOutOfRangeException(nameof(source), "The drum input source is not supported.");
             }
 
+            DrumArticulationValidator.EnsureValid(pad, articulation);
+
             Pad = pad;
             Velocity = velocity;
             SongTimeSeconds = songTimeSeconds;
             Source = source;
+            Articulation = articulation;
         }
 
         public DrumPad Pad { get; }
         public int Velocity { get; }
         public double SongTimeSeconds { get; }
         public DrumInputSource Source { get; }
+        public DrumArticulation Articulation { get; }
 
         public DrumInputEvent WithSongTime(double songTimeSeconds) =>
-            new DrumInputEvent(Pad, Velocity, songTimeSeconds, Source);
+            new DrumInputEvent(Pad, Velocity, songTimeSeconds, Source, Articulation);
     }
 }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Matching/HitMatchingSession.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Matching/HitMatchingSession.cs
index e292f27..8760b28 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Matching/HitMatchingSession.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Matching/HitMatchingSession.cs
@@ -52,7 +52,7 @@ public bool ProcessInput(DrumInputEvent input, out HitResult result)
         {
             lastInput = input;
             lastEventSongTimeSeconds = input.SongTimeSeconds;
-            var hit = new DrumHit(input.Pad, input.SongTimeSeconds, input.Velocity);
+            var hit = new DrumHit(input.Pad, input.SongTimeSeconds, input.Velocity, input.Articulation);
             bool matched = matcher.TryMatch(notes, hit, out result);
             if (matched)
             {
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
index 124f572..f777ab0 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartCreatorTests.cs
@@ -7,6 +7,7 @@
 using HitTheKit.Unity.Gameplay;
 using HitTheKit.Unity.Input;
 using NUnit.Framework;
+using UnityEngine;
 
 namespace HitTheKit.Unity.Tests
 {
@@ -131,6 +132,79 @@ public void Visual_editor_updates_adds_and_deletes_individual_notes_without_muta
                 Has.Count.EqualTo(2));
         }
 
+        [Test]
+        public void Visual_editor_and_json_round_trip_preserve_velocity_and_articulation()
+        {
+            var session = new ChartRecordingSession(8);
+            session.Record(Input(
+                DrumPad.Ride,
+                1,
+                73,
+                DrumInputSource.Midi,
+                DrumArticulation.Bow));
+            var editor = new ChartDraftEditor(session.Finish());
+
+            editor.Update(0, 1.25, DrumPad.Ride, 119, DrumArticulation.Bell);
+            editor.Add(2, DrumPad.Snare, 86, DrumArticulation.Rim);
+            LoadedChart loaded = new ChartLoader().Load(
+                ChartCreatorJson.Serialize(editor.BuildDraft(), "easy", 120, ChartQuantization.None),
+                "easy");
+
+            Assert.That(loaded.Notes.Select(note => (note.Velocity, note.Articulation)), Is.EqualTo(new[]
+            {
+                ((int?)119, DrumArticulation.Bell),
+                ((int?)86, DrumArticulation.Rim)
+            }));
+        }
+
+        [Test]
+        public void Waveform_envelope_scrubbing_and_zoom_are_deterministic_and_bounded()
+        {
+            float[] samples =
+            {
+                0.1f, -0.2f,
+                0.8f, 0.4f,
+                -0.5f, 0.3f,
+                1.0f, -0.9f
+            };
+            ChartWaveformModel first = ChartWaveformModel.FromInterleaved(samples, 2, 4, 4);
+            ChartWaveformModel second = ChartWaveformModel.FromInterleaved(samples, 2, 4, 4);
+
+            Assert.That(Enumerable.Range(0, first.PeakCount).Select(first.PeakAt),
+                Is.EqualTo(Enumerable.Range(0, second.PeakCount).Select(second.PeakAt)));
+            Assert.That(first.Scrub(0.5), Is.EqualTo(2).Within(0.000001));
+            first.Zoom(2);
+            Assert.That(first.ViewEndSeconds - first.ViewStartSeconds, Is.EqualTo(2).Within(0.000001));
+            Assert.That(first.SelectedTimeSeconds, Is.InRange(first.ViewStartSeconds, first.ViewEndSeconds));
+            Assert.That(first.Scrub(-1), Is.EqualTo(first.ViewStartSeconds));
+            Assert.That(first.Scrub(2), Is.EqualTo(first.ViewEndSeconds));
+            first.ResetZoom();
+            Assert.That((first.ViewStartSeconds, first.ViewEndSeconds), Is.EqualTo((0d, 4d)));
+        }
+
+        [Test]
+        public void Waveform_reads_the_complete_audio_clip_in_bounded_chunks()
+        {
+            AudioClip clip = AudioClip.Create("waveform-test", 1024, 1, 1024, false);
+            var samples = new float[1024];
+            samples[10] = 0.75f;
+            samples[900] = -1f;
+            Assert.That(clip.SetData(samples, 0), Is.True);
+
+            try
+            {
+                ChartWaveformModel model = ChartWaveformModel.FromAudioClip(clip, 8, 16);
+
+                Assert.That(model.PeakAt(0), Is.EqualTo(0.75f).Within(0.0001f));
+                Assert.That(model.PeakAt(7), Is.EqualTo(1f).Within(0.0001f));
+                Assert.That(model.DurationSeconds, Is.EqualTo(1).Within(0.0001));
+            }
+            finally
+            {
+                UnityEngine.Object.DestroyImmediate(clip);
+            }
+        }
+
         [Test]
         public void Visual_editor_rejects_invalid_indices_times_pads_and_velocity()
         {
@@ -143,6 +217,8 @@ public void Visual_editor_rejects_invalid_indices_times_pads_and_velocity()
             Assert.Throws<ArgumentOutOfRangeException>(() => editor.Update(0, 4.01, DrumPad.Kick));
             Assert.Throws<ArgumentOutOfRangeException>(() => editor.Update(0, 1, (DrumPad)999));
             Assert.Throws<ArgumentOutOfRangeException>(() => editor.Add(1, DrumPad.Snare, 128));
+            Assert.Throws<ArgumentException>(() =>
+                editor.Add(1, DrumPad.Kick, 100, DrumArticulation.Bell));
             Assert.Throws<ArgumentOutOfRangeException>(() => editor.Delete(2));
             Assert.That(editor.Notes, Has.Count.EqualTo(1));
         }
@@ -228,7 +304,8 @@ private static DrumInputEvent Input(
             DrumPad pad,
             double time,
             int velocity = 96,
-            DrumInputSource source = DrumInputSource.Keyboard) =>
-            new DrumInputEvent(pad, velocity, time, source);
+            DrumInputSource source = DrumInputSource.Keyboard,
+            DrumArticulation articulation = DrumArticulation.Default) =>
+            new DrumInputEvent(pad, velocity, time, source, articulation);
     }
 }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartLoaderTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartLoaderTests.cs
index 053c24f..10244fc 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartLoaderTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/ChartLoaderTests.cs
@@ -261,6 +261,43 @@ public void Preserves_duplicate_events_as_distinct_instances()
             Assert.That(ReferenceEquals(chart.Notes[0], chart.Notes[1]), Is.False);
         }
 
+        [Test]
+        public void Loads_optional_velocity_and_articulation_without_changing_legacy_notes()
+        {
+            LoadedChart chart = loader.Load(Chart(
+                "{\"time\":1,\"pad\":\"ride\",\"velocity\":112,\"articulation\":\"bell\"}," +
+                "{\"time\":2,\"pad\":\"snare\"}"), "easy");
+
+            Assert.That(chart.Notes[0].Velocity, Is.EqualTo(112));
+            Assert.That(chart.Notes[0].Articulation, Is.EqualTo(DrumArticulation.Bell));
+            Assert.That(chart.Notes[1].Velocity, Is.Null);
+            Assert.That(chart.Notes[1].Articulation, Is.EqualTo(DrumArticulation.Default));
+        }
+
+        [TestCase("0")]
+        [TestCase("128")]
+        [TestCase("null")]
+        public void Rejects_invalid_explicit_velocity(string value)
+        {
+            Assert.Throws<ChartLoadException>(() => loader.Load(
+                Chart($"{{\"time\":1,\"pad\":\"snare\",\"velocity\":{value}}}"), "easy"));
+        }
+
+        [TestCase("Bell")]
+        [TestCase("unknown")]
+        public void Rejects_unknown_or_incorrectly_cased_articulation(string articulation)
+        {
+            Assert.Throws<ChartLoadException>(() => loader.Load(
+                Chart($"{{\"time\":1,\"pad\":\"ride\",\"articulation\":\"{articulation}\"}}"), "easy"));
+        }
+
+        [Test]
+        public void Rejects_articulation_that_is_not_valid_for_the_selected_pad()
+        {
+            Assert.Throws<ChartLoadException>(() => loader.Load(
+                Chart("{\"time\":1,\"pad\":\"kick\",\"articulation\":\"bell\"}"), "easy"));
+        }
+
         private static string Chart(string notes, double offset = 0, int version = 1)
         {
             return $"{{\"version\":{version},\"offsetSeconds\":{offset.ToString(System.Globalization.CultureInfo.InvariantCulture)}," +
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/GameplayHighwayTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/GameplayHighwayTests.cs
index beb04a9..71dc4b6 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/GameplayHighwayTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/GameplayHighwayTests.cs
@@ -154,6 +154,28 @@ public void Kit_surface_explains_simultaneous_targets_in_beginner_language()
             Assert.That(surface.GuidanceText, Does.Contain("BORDO"));
         }
 
+        [TestCase(DrumArticulation.Bow, GameplayKitZone.Bow)]
+        [TestCase(DrumArticulation.Bell, GameplayKitZone.Bell)]
+        [TestCase(DrumArticulation.Edge, GameplayKitZone.Edge)]
+        public void Ride_chart_articulation_highlights_the_matching_physical_zone(
+            DrumArticulation articulation,
+            GameplayKitZone expectedZone)
+        {
+            string articulationId = articulation.ToString();
+            articulationId = char.ToLowerInvariant(articulationId[0]) + articulationId.Substring(1);
+            LoadedChart chart = new ChartLoader().Load(
+                "{\"version\":1,\"offsetSeconds\":0,\"difficulties\":{\"easy\":[" +
+                $"{{\"time\":1,\"pad\":\"ride\",\"velocity\":100,\"articulation\":\"{articulationId}\"}}" +
+                "]}}",
+                "easy");
+
+            GameplayKitTargetState state = new GameplayKitTargetStateCalculator().Calculate(
+                DrumPad.Ride, new ChartTimeline(chart).Notes, 0.5, 1, null, 0);
+
+            Assert.That(state.Zone, Is.EqualTo(expectedZone));
+            Assert.That(state.Intensity, Is.GreaterThan(0));
+        }
+
         [TestCase(DrumPad.Kick, GameplayKitZone.Pedal, "CASSA")]
         [TestCase(DrumPad.Snare, GameplayKitZone.Head, "RULLANTE")]
         [TestCase(DrumPad.HiHat, GameplayKitZone.Bow, "CHARLESTON")]
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/MidiKitMappingEngineTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/MidiKitMappingEngineTests.cs
index da454e4..2a448f4 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/MidiKitMappingEngineTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/EditMode/MidiKitMappingEngineTests.cs
@@ -174,6 +174,7 @@ public void Mvp_bridge_maps_supported_piece_articulations(
             Assert.That((drumInput.Pad, drumInput.Velocity, drumInput.SongTimeSeconds),
                 Is.EqualTo((expectedPad, 90, 3.25)));
             Assert.That(drumInput.Source, Is.EqualTo(DrumInputSource.Midi));
+            Assert.That(drumInput.Articulation, Is.EqualTo(ExpectedCoreArticulation(articulation)));
         }
 
         [Test]
@@ -223,6 +224,25 @@ private static NormalizedKitHit Hit(KitPiece piece, KitArticulation articulation
                 MidiMappingSource.BuiltInProfile);
         }
 
+        private static DrumArticulation ExpectedCoreArticulation(KitArticulation articulation)
+        {
+            switch (articulation)
+            {
+                case KitArticulation.Default: return DrumArticulation.Default;
+                case KitArticulation.Head: return DrumArticulation.Head;
+                case KitArticulation.Rim: return DrumArticulation.Rim;
+                case KitArticulation.Bow: return DrumArticulation.Bow;
+                case KitArticulation.Edge: return DrumArticulation.Edge;
+                case KitArticulation.Bell: return DrumArticulation.Bell;
+                case KitArticulation.Closed: return DrumArticulation.Closed;
+                case KitArticulation.HalfOpen: return DrumArticulation.HalfOpen;
+                case KitArticulation.Open: return DrumArticulation.Open;
+                case KitArticulation.Pedal: return DrumArticulation.Pedal;
+                case KitArticulation.Choke: return DrumArticulation.Choke;
+                default: throw new ArgumentOutOfRangeException(nameof(articulation));
+            }
+        }
+
         private static KitElement Element(string id, KitPiece piece, KitArticulation articulation)
         {
             return new KitElement(id, piece, articulation, id);
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/GameplayHighwayPlayModeTests.cs b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/GameplayHighwayPlayModeTests.cs
index 948d6d5..63d14ef 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/GameplayHighwayPlayModeTests.cs
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/Tests/PlayMode/GameplayHighwayPlayModeTests.cs
@@ -58,6 +58,10 @@ public IEnumerator Gameplay_scene_uses_the_session_theme_and_does_not_expose_an_
             Assert.That(document.rootVisualElement.Q<VisualElement>("results-overlay"), Is.Not.Null);
             Assert.That(document.rootVisualElement.Q<Button>("pause-button"), Is.Not.Null);
             Assert.That(document.rootVisualElement.Q<VisualElement>("countdown-overlay"), Is.Not.Null);
+            Assert.That(document.rootVisualElement.Q<ChartWaveformView>("chart-waveform"), Is.Not.Null);
+            Assert.That(document.rootVisualElement.Q<Button>("chart-waveform-preview"), Is.Not.Null);
+            Assert.That(document.rootVisualElement.Q<TextField>("chart-note-velocity"), Is.Not.Null);
+            Assert.That(document.rootVisualElement.Q<DropdownField>("chart-note-articulation"), Is.Not.Null);
             Assert.That(controller.CountdownBeat, Is.InRange(1, 4));
             Assert.That(controller.Theme, Is.EqualTo(GameplayPresentationTheme.ConcertStage));
             Assert.That(app.ClassListContains("theme--concert-stage"), Is.True);
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
index b8a60fa..51db797 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uss
@@ -542,15 +542,21 @@
 .chart-creator-actions { margin-top: 10px; flex-direction: row; justify-content: center; }
 .chart-save-button { width: 170px; min-height: 38px; margin: 0 4px; }
 .chart-creator-status { min-height: 20px; margin-top: 8px; color: rgb(78, 221, 137); font-size: 10px; -unity-font-style: bold; white-space: normal; -unity-text-align: middle-center; }
-.chart-note-editor { height: 250px; margin-top: 10px; flex-direction: row; }
+.chart-waveform-panel { height: 116px; margin-top: 8px; }
+.chart-waveform-host { height: 82px; border-width: 1px; border-color: rgba(65, 219, 255, 0.72); border-radius: 4px; overflow: hidden; }
+.chart-waveform-toolbar { height: 30px; margin-top: 4px; flex-direction: row; align-items: center; }
+.chart-waveform-time { min-width: 126px; color: rgb(91, 224, 255); font-size: 9px; -unity-font-style: bold; }
+.chart-waveform-button { height: 26px; min-width: 62px; margin-left: 4px; padding-left: 6px; padding-right: 6px; border-width: 1px; border-color: rgba(74, 138, 168, 0.8); background-color: rgba(9, 24, 36, 0.98); color: white; font-size: 8px; -unity-font-style: bold; }
+.chart-waveform-preview { min-width: 100px; border-color: rgb(255, 174, 56); color: rgb(255, 207, 133); }
+.chart-note-editor { height: 226px; margin-top: 8px; flex-direction: row; }
 .chart-note-list { width: 48%; height: 100%; border-width: 1px; border-color: rgba(74, 138, 168, 0.7); background-color: rgba(2, 10, 18, 0.9); }
 .chart-note-list .unity-list-view__item { padding-left: 8px; color: white; border-bottom-width: 1px; border-bottom-color: rgba(74, 138, 168, 0.28); }
 .chart-note-list .unity-collection-view__item--selected { background-color: rgba(24, 151, 190, 0.75); }
 .chart-note-controls { width: 52%; padding-left: 12px; }
 .chart-note-selection { min-height: 22px; color: rgb(91, 224, 255); font-size: 11px; -unity-font-style: bold; }
 .chart-note-fields { margin-top: 5px; }
-.chart-note-time, .chart-note-pad { margin-top: 5px; color: white; }
-.chart-note-time .unity-text-input, .chart-note-pad .unity-base-field__input { background-color: rgba(9, 24, 36, 0.98); border-width: 1px; border-color: rgb(52, 86, 108); color: white; }
+.chart-note-time, .chart-note-pad, .chart-note-velocity, .chart-note-articulation { margin-top: 3px; color: white; }
+.chart-note-time .unity-text-input, .chart-note-pad .unity-base-field__input, .chart-note-velocity .unity-text-input, .chart-note-articulation .unity-base-field__input { background-color: rgba(9, 24, 36, 0.98); border-width: 1px; border-color: rgb(52, 86, 108); color: white; }
 .chart-note-buttons { margin-top: 8px; flex-direction: row; }
 .chart-note-button { min-width: 88px; height: 34px; min-height: 34px; margin: 0 3px; font-size: 9px; }
 .chart-note-delete { border-color: rgb(241, 91, 104); color: rgb(255, 148, 158); }
diff --git a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
index a025399..6e497f5 100644
--- a/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
+++ b/src/HitTheKit.Unity/Assets/HitTheKit/UI/Gameplay/GameplayHighway.uxml
@@ -126,7 +126,18 @@
                 <ui:VisualElement name="chart-creator-results" class="chart-creator-results" style="display: none;">
                     <ui:Label text="REVISIONE TAKE" class="eyebrow chart-creator-eyebrow" />
                     <ui:Label name="chart-creator-summary" text="0 COLPI REGISTRATI" class="chart-creator-summary" />
-                    <ui:Label text="Seleziona una nota per correggere tempo o strumento. Il pacchetto .htksong resta senza audio." class="chart-creator-copy" />
+                    <ui:Label text="Seleziona una nota per correggere tempo, dinamica e articolazione. Il pacchetto .htksong resta senza audio." class="chart-creator-copy" />
+                    <ui:VisualElement class="chart-waveform-panel">
+                        <ui:VisualElement name="chart-waveform-host" class="chart-waveform-host" />
+                        <ui:VisualElement class="chart-waveform-toolbar">
+                            <ui:Label name="chart-waveform-time" text="PLAYHEAD 0.000s" class="chart-waveform-time" />
+                            <ui:Button name="chart-waveform-zoom-in" text="ZOOM +" class="chart-waveform-button" />
+                            <ui:Button name="chart-waveform-zoom-out" text="ZOOM −" class="chart-waveform-button" />
+                            <ui:Button name="chart-waveform-reset" text="TUTTO" class="chart-waveform-button" />
+                            <ui:Button name="chart-waveform-preview" text="ASCOLTA DA QUI" class="chart-waveform-button chart-waveform-preview" />
+                            <ui:Button name="chart-waveform-stop" text="STOP" class="chart-waveform-button" />
+                        </ui:VisualElement>
+                    </ui:VisualElement>
                     <ui:VisualElement class="chart-note-editor">
                         <ui:ListView name="chart-note-list" class="chart-note-list" />
                         <ui:VisualElement class="chart-note-controls">
@@ -134,6 +145,8 @@
                             <ui:VisualElement class="chart-note-fields">
                                 <ui:TextField name="chart-note-time" label="TEMPO (s)" class="chart-note-time" />
                                 <ui:DropdownField name="chart-note-pad" label="STRUMENTO" class="chart-note-pad" />
+                                <ui:TextField name="chart-note-velocity" label="VELOCITY (1–127)" class="chart-note-velocity" />
+                                <ui:DropdownField name="chart-note-articulation" label="ARTICOLAZIONE" class="chart-note-articulation" />
                             </ui:VisualElement>
                             <ui:VisualElement class="chart-note-buttons">
                                 <ui:Button name="chart-note-add" text="AGGIUNGI" class="run-secondary-button chart-note-button" />
diff --git a/tests/HitTheKit.Core.Tests/HitMatcherTests.cs b/tests/HitTheKit.Core.Tests/HitMatcherTests.cs
index fdcedd6..03fe7e4 100644
--- a/tests/HitTheKit.Core.Tests/HitMatcherTests.cs
+++ b/tests/HitTheKit.Core.Tests/HitMatcherTests.cs
@@ -108,6 +108,47 @@ public void Hit_on_wrong_pad_does_not_resolve_note()
         Assert.NotNull(correctPadResult);
     }
 
+    [Fact]
+    public void Articulation_specific_note_rejects_a_different_zone_without_resolving_it()
+    {
+        var matcher = new HitMatcher(TimingWindows.Default);
+        var note = new ChartNote(1.000, DrumPad.Ride, 110, DrumArticulation.Bell);
+        ChartNote[] notes = { note };
+
+        Assert.False(matcher.TryMatch(
+            notes,
+            new DrumHit(DrumPad.Ride, 1.000, 110, DrumArticulation.Bow),
+            out HitResult? wrongZone));
+        Assert.Null(wrongZone);
+        Assert.True(matcher.TryMatch(
+            notes,
+            new DrumHit(DrumPad.Ride, 1.000, 110, DrumArticulation.Bell),
+            out HitResult? correctZone));
+        Assert.NotNull(correctZone);
+    }
+
+    [Fact]
+    public void Default_articulation_remains_a_backward_compatible_wildcard()
+    {
+        var note = new ChartNote(1.000, DrumPad.Snare);
+
+        HitResult result = Match(
+            new HitMatcher(TimingWindows.Default),
+            new[] { note },
+            new DrumHit(DrumPad.Snare, 1.000, 100, DrumArticulation.Rim));
+
+        Assert.Equal(HitGrade.Perfect, result.Grade);
+    }
+
+    [Fact]
+    public void Chart_note_rejects_invalid_velocity_and_pad_articulation_pairs()
+    {
+        Assert.Throws<ArgumentOutOfRangeException>(() => new ChartNote(1, DrumPad.Snare, 0));
+        Assert.Throws<ArgumentOutOfRangeException>(() => new ChartNote(1, DrumPad.Snare, 128));
+        Assert.Throws<ArgumentException>(() =>
+            new ChartNote(1, DrumPad.Kick, 100, DrumArticulation.Bell));
+    }
+
     [Fact]
     public void Expired_note_is_miss()
     {