Pulse Editor - Documentation

1. Overview

The Pulse Editor is a core component of the SonicSyncSail experience, designed to allow users to isolate emotionally meaningful moments within a song by creating Pulse Segments. These segments represent carefully defined audio ranges marked by a start timestamp, an end timestamp, emotional category, emotion tags, and an intensity level.

The Pulse Editor provides advanced tools for selecting these ranges, including looping preview playback, waveform visualization (MP3-only), precision timestamp adjustments, and DSP-driven acoustic analysis. Saved segments become part of the user’s emotional library and serve as the foundation for the PulseSync engine, which stitches emotional fragments across songs into seamless mixes.

2. Purpose and User Value

The Pulse Editor transforms a traditional music library into a personal emotional archive. Instead of consuming entire songs, users can capture only the moments that resonate most deeply.

• Drops
• Riffs
• Climactic vocal lines
• Emotional transitions
• High-energy or introspective moments

These curated emotional fragments fuel PulseSync’s continuous mood-driven playback system. Users gain the ability to define the exact emotional meaning of a moment, categorize it, and give it intensity—resulting in a personalized and emotionally intelligent listening experience.

3. Technical Architecture

3.1 Segmentation Engine

Every Pulse Segment is stored with detailed metadata, including:

• songId
• startMs
• endMs
• emotionCategory
• emotionTag
• intensityLevel (Low / Medium / High)
• autoIntensityDetected (true/false)
• timestamps (createdAt, updatedAt)

All data is stored in a dedicated Room Database table optimized for fast PulseSync retrieval.

3.2 Waveform Generation (MP3 Only)

• Downsampled PCM extraction
• Asynchronous waveform generation
• Amplitude windowing
• Multipoint cached waveform
• Custom overlay UI with draggable handles

Waveform mode also enables auto emotion intensity detection through DSP analysis.

3.3 Slider-Based Segment Selection

Lightweight dual-handle sliders allow fast segment selection. This mode is available for all audio formats but does not support auto intensity detection.

3.4 Precision Adjustment Controls

Six arrow-based controls allow precise timestamp adjustment with long-press acceleration:

• << Move left handle left by 1 sec
• >> Move left handle right by 1 sec
• <-- Shift entire selection left
• --> Shift entire selection right
• << Move right handle left by 1 sec
• >> Move right handle right by 1 sec

3.5 Loop Playback (Media3 ExoPlayer)

The preview player loops precisely within the selected range and resets to start whenever timestamps change, enabling musical and emotional fine-tuning.

3.6 Emotion Processing & DSP

In waveform mode, DSP analysis computes:

• BPM
• Relative loudness
• Micro-dynamics
• Energy peaks

This maps to an intensity level of Low, Medium, or High.

3.7 Update Mode

If editing an existing segment, the editor loads all settings, enables “Update Segment,” and tracks modifications before allowing saves.

3.8 Invocation Sources

Pulse Editor can be opened from:

• Home
• Library
• Album / Artist / Genre pages
• Song overflow menu
• PulseVault

Opening from PulseVault loads directly into update mode.

4. User Interface & Experience

4.1 Info Section

• Album art
• Song title
• Full duration
• “Enable Segment Creation” toggle
• “New Segment” button

4.2 Pulse Clipper Section

4.2.1 Selection Method Toggle

Users choose between Slider View and Waveform View.

4.2.2 Slider View

Dual-handle slider for quick selection; no auto-intensity detection.

4.2.3 Waveform View

MP3-only, detailed waveform with draggable handles and cached amplitude data.

4.2.4 Precision Controls

All six adjustment controls support long-press acceleration.

4.2.5 Loop Preview Playback

Looped ExoPlayer preview with timestamp indicators, seek bar, and play/pause controls.

4.3 Pulse Settings Section

4.3.1 Emotion Categories

Displayed as Material chips. Categories include Positive, Romantic, Calm, Sad, Dark, Party, Epic, and more.

4.3.2 Emotion Tags

Users must choose at least one tag appropriate to the emotion category.

4.3.3 Emotion Intensity

Intensity values: Low, Medium, High. Auto-detected in waveform mode; manual in slider mode.

Why intensity matters: Intensity provides a compact representation of pulse energy (bpm proxy, loudness and transient activity). The PulseMixer uses intensity to prefer smoother transitions between segments by selecting pulses with matching intensity for consecutive mixes.

4.3.4 Save / Update Controls

Save is disabled until changes are detected.

4.4 Available Segments Section

• List of created segments
• Delete All with confirmation
• Delete individual segment
• Tapping loads the segment into update mode

5. Data Flow

5.1 Loading a Song

Loaded from Library, Album/Artist pages, PulseVault, or Home.

5.2 Creating a Segment

Timestamp selection → Emotion tag selection → Save to Room DB.

5.3 Updating a Segment

Loads all values → user updates → commits changes.

5.4 Deleting Segments

Supports single deletion or delete all.

6. Edge Cases and Safeguards

• Zero-length segments blocked
• Negative-length segments blocked
• Waveform mode requires MP3
• Short segments (500 ms) blocked
• Auto-intensity disabled in slider mode
• Save disabled until changes detected
• Permissions checked before waveform generation
• Long-press acceleration limited for safety

7. Known Limitations

• Waveform mode supports MP3 only
• DSP intensity detection is approximate
• No overlap management for segments
• No batch editing support
• No undo/redo
• No beat snapping