History Management

VozCraft automatically maintains a comprehensive history of all your generated audio, allowing you to replay, rename, export, and manage your text-to-speech creations. This guide covers all history features and best practices for organizing your audio library.

Overview

Every audio generation is automatically saved to your history with complete metadata:

Automatic Saving

Every generated audio is instantly added to history with all settings preserved

30 Item Limit

History maintains your 30 most recent audio generations

Browser Storage

History persists in browser local storage across sessions

History Panel

Location and Display

The history panel is located:

Desktop: Right side of the screen (fixed width: 340px)
Tablet: Below the main control panel
Mobile: Below the main control panel

Panel Components

Header
Scroll Area
Footer Buttons

History Header displays:

📋 History (15)
[Clear all]

Title: ”📋 Historial” (Spanish) or ”📋 History” (English)
Count: Number of items in parentheses (e.g., “(15)”)
Clear Button: Red “Limpiar todo” / “Clear all” button

The count badge updates automatically as you add or remove items.

Scrollable Content Area:

Height: Flexible, min 280px, max 60vh (60% of viewport height)
Scroll Behavior: Smooth scrolling with custom scrollbar
Empty State: Shows microphone icon and message when empty
Item Order: Newest first (reverse chronological)

Empty State Message:

🎤
Aún no has generado audios
(You have not generated audios yet)

History Items

Each history item is a comprehensive record of a single audio generation:

Item Structure

{
  id: "1705349100000",           // Timestamp as string
  timestamp: 1705349100000,      // Unix timestamp (milliseconds)
  texto: "Welcome to VozCraft...", // Complete text content
  nombre: "My Audio Name",       // Custom name (empty string if not set)
  voz: "Español (México)",         // Language/accent selection
  genero: "Voz Normal",           // Voice type (Normal/High-pitched)
  velocidad: "Normal",            // Speed setting
  animo: "Neutral"                // Mood setting
}

Visual Display

Each history item shows:

Name Row

Audio Name + Edit Button

Left: Bold name or auto-generated “Audio · [date/time]”
Right: ✏️ Edit button (24x24px)

My Audio Name                                    ✏️

Truncates with ellipsis if too long
Edit button changes color on hover (blue)

Metadata Row

Date · Voice · Type · Speed · MoodExample:

🗃 1/15/2026, 3:45 PM · Español (México) · Voz Normal · Normal · Neutral

Small text (11px)
Secondary color (muted)
Separated by bullets (·)
Wraps on mobile
Adapts to selected interface language

Text Preview

First Line of Text

Welcome to VozCraft, the most advanced text-to-speech...

Single line with ellipsis
Shows beginning of transcript
Helps identify content quickly

Action Buttons

Button Row

[▶ Reproducir] [MP3] [WAV] [📄 TXT] [✕]

Five buttons:

Play/Stop (blue/purple) - Flex-grow, main action
MP3 (green) - Export as MP3
WAV (amber) - Export as WAV
TXT (purple) - Download transcript
Delete (red) - Remove from history

Buttons wrap on narrow screens.

Audio Player (When Playing)

Inline Player ComponentAppears below buttons when audio is playing:

Progress Bar: Seekable with position indicator
Play/Pause Button: 32px circular button
Waveform Visualization: 32 animated bars
Time Display: “0:45 / 2:30” format

Blue gradient background indicates active playback.

Visual States

Default State
Playing State
Hover State

Not Playing:

Light background (white or dark card color)
Standard border
”▶ Reproducir” / ”▶ Play” button
No audio player visible

Purpose: Compact display to show more items in limited space.

Currently Playing:

Blue-tinted background (rgba(37,99,235,0.08) dark, #f0f7ff light)
Blue border (rgba(37,99,235,0.3) dark, #bfdbfe light)
”⏹ Detener” / ”⏹ Stop” button (purple gradient)
Audio player visible with waveform
Progress bar animating

Purpose: Clear visual indicator of active audio.

Renaming Audio

VozCraft allows you to assign custom names to your audio for better organization:

Default Naming

When audio is first generated, it has no custom name (nombre: ""), so it displays:

Audio · 1/15/2026, 3:45 PM

Format: "Audio · " + localized_date_time

Rename Process

Open Rename Modal

Click the ✏️ (pencil) icon next to the audio name.A modal dialog appears:

Centered overlay with backdrop blur
Title: “✏️ Nombre del audio” / “✏️ Audio name”
Text input with current name pre-filled
Input is auto-focused and text is selected

Enter New Name

Type your desired name in the input field:

Maximum length: 80 characters
Allowed characters: All characters accepted
Placeholder: “Escribe un nombre…” / “Enter a name…”

Good naming examples:

“Product Demo Script v2”
“Spanish Lesson 1 - Greetings”
“Podcast Intro - Season 2”
“Training Module 5”
“Customer Service Script - Returns”

Save or Cancel

Three ways to confirm:

Click Save Button: “Guardar” / “Save” (blue gradient)
Press ENTER: Quick-save shortcut
Press ESC: Cancel (no changes)

Or click “Cancelar” / “Cancel” button or backdrop to abort.

Confirmation

After saving:

Modal closes immediately
Name updates in history item
Toast notification: ”✓ Nombre actualizado” / ”✓ Name updated”
History is saved to browser storage
New name will be used for file exports

// Modal component structure
<RenameModal>
  <Overlay onClick={onCancel} />  // Click outside to close
  <Dialog>
    <Title>✏️ {t.renameTitle}</Title>
    <Input 
      maxLength={80}
      value={currentName}
      autoFocus
      autoSelect
      onEnter={confirm}
      onEscape={cancel}
    />
    <ButtonRow>
      <SaveButton />   // Blue gradient, calls onConfirm
      <CancelButton /> // Gray, calls onCancel
    </ButtonRow>
  </Dialog>
</RenameModal>

Naming Strategy: Use descriptive names that help you identify content later. Include version numbers, dates, or project names for better organization.

Playback from History

Playing Audio

Click the ”▶ Reproducir” / ”▶ Play” button on any history item:

Audio Begins Playing

Button changes to ”⏹ Detener” / ”⏹ Stop” with purple gradient
Item background becomes blue-tinted
Inline audio player appears below buttons
Web Speech API synthesizes audio with original settings

Audio Player Features

Progress Bar:

Visual progress indicator (5px height)
Seekable - click anywhere to jump to position
Animated position dot follows progress
Gradient fill (blue to purple)

Waveform Visualization:

32 vertical bars
Varying heights (20-90%) for visual interest
Bars animate when playing
Color changes: blue for played, gray for upcoming
Animation: wave-bar-mini keyframes, 0.6-1.08s duration

Time Display:

Format: “0:45 / 2:30” (current / total)
Updates 10 times per second (100ms interval)
Tabular numbers for alignment
Gray text color

Playback Controls

Play/Pause Button (32px circle):

Playing: Shows ⏸ (pause icon), purple background
Paused: Shows ▶ (play icon), blue background
Click to toggle playback state

Seek Functionality:

Click progress bar to jump to position
Audio restarts from clicked position
Useful for long audio content

Stopping Playback

Click ”⏹ Detener” or play another audio:

Current audio stops immediately
Button reverts to ”▶ Reproducir”
Player remains visible until item changes
Background color returns to normal

Duration Calculation

VozCraft estimates duration based on text length and settings:

// Duration estimation algorithm
const effectiveRate = (baseRate + voiceTypeRateAdd) * moodRateMulti;
const estimatedDuration = Math.max(1, textLength / (14 * effectiveRate));

// Where:
// - baseRate: From VELOCIDADES (0.50 to 1.60)
// - voiceTypeRateAdd: From GENEROS (-0.05 or +0.05)
// - moodRateMulti: From ANIMOS (0.78 to 1.30)
// - textLength: Character count
// - 14: Average characters spoken per second at normal rate

Example Calculations:

Example 1: Normal Settings

Settings:

Text: 700 characters
Speed: Normal (1.00)
Voice Type: Normal (-0.05)
Mood: Neutral (1.00x)

Calculation:

effectiveRate = (1.00 + (-0.05)) * 1.00 = 0.95
duration = 700 / (14 * 0.95) = 700 / 13.3 = 52.6 seconds

Result: ~53 seconds of audio

Example 2: Fast & Energetic

Settings:

Text: 1000 characters
Speed: Fast (1.25)
Voice Type: High-pitched (+0.05)
Mood: Energetic (1.30x)

Calculation:

effectiveRate = (1.25 + 0.05) * 1.30 = 1.30 * 1.30 = 1.69
duration = 1000 / (14 * 1.69) = 1000 / 23.66 = 42.3 seconds

Result: ~42 seconds of audio (fast!)

Example 3: Slow & Melancholic

Settings:

Text: 500 characters
Speed: Slow (0.75)
Voice Type: Normal (-0.05)
Mood: Melancholic (0.78x)

Calculation:

effectiveRate = (0.75 + (-0.05)) * 0.78 = 0.70 * 0.78 = 0.546
duration = 500 / (14 * 0.546) = 500 / 7.64 = 65.4 seconds

Result: ~65 seconds (very slow and contemplative)

Deleting History Items

Delete Single Item

Remove individual history items:

Click Delete Button

Click the red ✕ button on the history item you want to remove.

Immediate Removal

Item disappears from history instantly
No confirmation dialog (action is immediate)
Remaining items re-flow to fill space
History count updates (e.g., “(15)” becomes “(14)”)
Browser storage updated

Confirmation Toast

Toast notification appears:

Spanish: “Eliminado del historial”
English: “Removed from history”
Green background (success)
Auto-dismisses after 3.2 seconds

No Undo: Deleting a history item is permanent. The audio settings and text are lost unless you’ve exported the history JSON or individual files.

Clear All History

Remove all history items at once:

Click Clear All Button

Click the red “Limpiar todo” / “Clear all” button in the history header.

Immediate Clearing

All history items removed instantly
No confirmation dialog
Empty state message appears
Count badge disappears
“Clear all” button hides (only visible when history exists)

Storage Cleared

Browser local storage cleared
No way to undo this action
Toast: “Historial limpiado” / “History cleared”

Data Loss Risk: Clearing all history is permanent and cannot be undone. Always export your history JSON before clearing if you might need it later.

Exporting History (JSON)

Export Process

Save your entire history as a JSON file:

Click Save Button

Click the ”💾 Guardar” / ”💾 Save” button at the bottom of the history panel.

File Generation

VozCraft generates a JSON file:

Filename: vozcraft-historial.json
Format: Pretty-printed JSON (2-space indentation)
Encoding: UTF-8
Contains array of all history items

Download

Browser download begins:

File saves to default Downloads folder
No processing delay (instant)
Toast notification: ”📁 Historial exportado”

JSON File Structure

[
  {
    "id": "1705349100000",
    "timestamp": 1705349100000,
    "texto": "Welcome to VozCraft, the most advanced text-to-speech application.",
    "nombre": "Demo Audio v1",
    "voz": "English (US)",
    "genero": "Voz Normal",
    "velocidad": "Normal",
    "animo": "Neutral"
  },
  {
    "id": "1705349050000",
    "timestamp": 1705349050000,
    "texto": "Bienvenido a VozCraft, la aplicación de texto a voz más avanzada.",
    "nombre": "Audio de Prueba",
    "voz": "Español (México)",
    "genero": "Voz Aguda",
    "velocidad": "Rápido",
    "animo": "Alegre"
  }
]

Array Structure:

Top-level: Array of objects
Each object: One history item
Order: Newest first (reverse chronological)
All fields preserved exactly as stored

Use Cases for JSON Export

Backup

Prevent data loss: Export regularly to preserve your work
Browser changes: Protect against browser data clearing
Migration: Move history to another device
Archive: Long-term storage of audio metadata

Sharing

Team collaboration: Share audio library with colleagues
Project handoff: Transfer work to another team member
Templates: Share commonly-used audio settings
Documentation: Include in project documentation

Analysis

Content audit: Review what content has been generated
Statistics: Analyze language/mood/speed usage
Search: Find specific content across all generations
Reporting: Generate reports on TTS usage

Recovery

Restore after clearing: Recover accidentally cleared history
Device failure: Restore history after hardware issues
Browser reset: Recover after clearing browser data
Experimentation: Try different settings, revert to backup

Importing History (JSON)

Import Process

Restore or merge history from a JSON file:

Click Load Button

Click the ”📂 Cargar” / ”📂 Load” button at the bottom of the history panel.

Select File

Browser file picker opens:

File filter: .json files only
Navigate to your history file
Select vozcraft-historial.json (or renamed file)
Click “Open”

Processing

VozCraft reads and validates the file:

Parses JSON content
Validates structure (must be array)
Checks for required fields in each item
Handles errors gracefully

Merge with Existing History

Imported items are merged with current history:

New items added to existing history
Duplicates possible (based on ID collision)
Combined history limited to 30 most recent items
Items sorted by timestamp (newest first)

Success Confirmation

Toast notification shows:

Message: ”✓ [X] entradas cargadas” / ”✓ [X] entries loaded”
X = number of items in imported file
Green background (success)
History panel updates immediately

Import Behavior

Merge Logic
Error Handling
Duplicate Handling

How Import Merges with Existing History:

// Pseudo-code for import logic
function handleLoadHistory(importedArray) {
  if (!Array.isArray(importedArray)) {
    showError("Invalid file format");
    return;
  }
  
  // Add to existing history
  const newHistory = [...importedArray, ...currentHistory];
  
  // Limit to 30 items (most recent)
  const trimmed = newHistory.slice(0, 30);
  
  setHistory(trimmed);
  saveToStorage(trimmed);
  showToast(`✓ ${importedArray.length} entries loaded`);
}

Important Notes:

Import does NOT replace existing history
Import ADDS to existing history
To replace completely, clear history first, then import
30-item limit applies after merging

When Importing Contains Duplicates:VozCraft does not deduplicate on import:

Items with same ID can exist multiple times
Each is treated as separate history item
Display shows all copies

To Avoid Duplicates:

Clear history before importing
Or manually edit JSON to remove duplicates
Or accept duplicates and delete manually after import

ID Structure:

IDs are timestamps: Date.now().toString()
Collisions only if generated at exact same millisecond
In practice, very rare

Valid JSON Format

For manual JSON creation or editing:

[
  {
    "id": "1705349100000",        // Required: String timestamp
    "timestamp": 1705349100000,   // Required: Number timestamp
    "texto": "Your text here",    // Required: String
    "nombre": "Custom Name",      // Required: String (empty string if no name)
    "voz": "Español (México)",    // Required: Must match VOCES labels
    "genero": "Voz Normal",       // Required: "Voz Normal" or "Voz Aguda"
    "velocidad": "Normal",        // Required: Must match VELOCIDADES labels
    "animo": "Neutral"            // Required: Must match ANIMOS labels
  }
]

Field Validation:

Field	Type	Valid Values	Notes
`id`	string	Any string	Used as React key, typically timestamp
`timestamp`	number	Unix timestamp	Milliseconds since epoch
`texto`	string	Any text	1-5000 characters recommended
`nombre`	string	Any text	0-80 characters, empty string if unnamed
`voz`	string	VOCES labels	Must match exactly
`genero`	string	”Voz Normal” or “Voz Aguda”	Case-sensitive
`velocidad`	string	VELOCIDADES labels	Must match exactly
`animo`	string	ANIMOS labels	Must match exactly

Label Matching: Voice, speed, and mood values must exactly match the labels in VozCraft’s source code. Mismatched values will cause the audio to use default settings instead.

History Limit and Rotation

30-Item Maximum

VozCraft maintains a maximum of 30 history items:

// History limit implementation
const MAX_HISTORY_ITEMS = 30;

const newHistory = [item, ...history].slice(0, MAX_HISTORY_ITEMS);
setHistory(newHistory);
saveHistory(newHistory);

Behavior:

New items added to beginning of array
When adding 31st item, oldest (30th) is removed
FIFO queue: First In, First Out
Automatic rotation maintains limit

Why 30 Items? This limit balances functionality with performance and storage concerns:

Prevents excessive browser storage usage
Keeps UI responsive with reasonable scroll depth
Encourages users to export important histories
Typical use case: Keep recent work, export archives

Managing the Limit

Monitor Your History

Watch the count in the history header:

Approaches 30: Consider exporting or cleaning
Reaches 30: Oldest items will be auto-removed
Over 30: Not possible (enforced by code)

Export Before Limit

Before reaching 30 items:

Export current history to JSON
Clear history if starting fresh project
Import only items you need from archive

Curate Your History

Manually manage important items:

Delete test generations
Remove duplicates or mistakes
Rename important items for easy identification
Export individual audio files you want to keep

Best Practice: Export your history JSON weekly or after each major project. This creates a permanent archive while keeping your active history clean and focused.

Browser Storage Details

Local Storage Implementation

VozCraft uses the browser’s localStorage API:

// Storage key
const STORAGE_KEY = 'vozcraft-history';

// Save operation
await window.storage.set(STORAGE_KEY, JSON.stringify(historyArray));

// Load operation
const result = await window.storage.get(STORAGE_KEY);
if (result?.value) {
  const history = JSON.parse(result.value);
  setHistory(history);
}

Storage Characteristics

Persistence

Survives: Browser restarts, computer restarts
Lost on: Clearing browser data, incognito mode end
Per-domain: Isolated to VozCraft’s domain
Capacity: Typically 5-10 MB per domain

Automatic Operations

Save on: Every generation, rename, delete, import
Load on: Page load, browser refresh
No user action: Completely transparent
Error handling: Graceful degradation if storage fails

Storage Size Estimate

Typical History Item Size:

{
  id: 16 bytes
  timestamp: 8 bytes
  texto: ~500 bytes average (500 character text)
  nombre: ~50 bytes average (25 character name)
  voz: ~30 bytes
  genero: ~15 bytes
  velocidad: ~15 bytes
  animo: ~15 bytes
}
Total per item: ~650 bytes average

30 Items: ~19.5 KB (well within limits) 5000 Character Texts: ~165 KB for 30 items with max-length texts

VozCraft’s history storage is very efficient. Even with maximum-length texts and 30 items, storage usage is minimal compared to typical localStorage capacity.

Clearing Browser Storage

History is lost when:

Clearing Browser Data

Manual Clear (Chrome/Edge):

Settings > Privacy and Security
Clear browsing data
Select “Cookies and other site data”
Choose time range
Click “Clear data”

Result: VozCraft history permanently deletedPrevention: Export history JSON before clearing browser data

Incognito/Private Mode

Behavior:

History saves during incognito session
History deleted when incognito window closes
Not shared with normal browsing mode
No persistence between sessions

Use Case: Temporary generations that should not persist

Different Browsers

Cross-Browser:

Each browser has separate localStorage
History in Chrome ≠ History in Firefox
No automatic synchronization

Migration: Export JSON from Browser A, import in Browser B

Troubleshooting History Issues

History Not Saving: If your history disappears after page refresh, check:

Browser isn’t in incognito/private mode
Browser storage isn’t full
Site permissions allow storage
No browser extensions blocking storage

History disappeared

Possible Causes:

Browser data cleared
Using different browser/profile
Incognito mode used
Storage quota exceeded (rare)
Browser extension interference

Solutions:

Check if you have an exported JSON backup
Verify you’re using the same browser and profile
Disable browser extensions and test
Check browser storage settings

Prevention: Export history JSON regularly

Can't import history file

Error: “Error al leer el archivo”Causes:

File is not valid JSON
File is corrupted
Top-level is not an array
File encoding issues

Solutions:

Verify file opens in text editor
Check JSON validity with online validator
Ensure file exported from VozCraft
Try re-exporting from original source

Imported history looks wrong

Items show default values or errorsCauses:

Field names don’t match expected format
Language/voice labels don’t match VOCES array
Speed/mood labels don’t match arrays
Missing required fields

Solutions:

Only import files exported by VozCraft
If manually editing, match labels exactly
Check source code arrays for valid values
Re-export from working VozCraft instance

Next Steps

Audio Export

Learn about exporting audio as MP3, WAV, and TXT files

Using VozCraft

Complete guide to VozCraft workflows

Troubleshooting

Solutions to common issues and problems

Get Started

Features

Guides

​History Management

​Overview

Automatic Saving

30 Item Limit

Browser Storage

​History Panel

​Location and Display

​Panel Components

​History Items

​Item Structure

​Visual Display

​Visual States

​Renaming Audio

​Default Naming

​Rename Process

​Rename Modal Details

​Playback from History

​Playing Audio

​Duration Calculation

​Deleting History Items

​Delete Single Item

​Clear All History

​Exporting History (JSON)

​Export Process

​JSON File Structure

​Use Cases for JSON Export

Backup

Sharing

Analysis

Recovery

​Importing History (JSON)

​Import Process

​Import Behavior

​Valid JSON Format

​History Limit and Rotation

​30-Item Maximum

​Managing the Limit

​Browser Storage Details

​Local Storage Implementation

​Storage Characteristics

Persistence

Automatic Operations

​Storage Size Estimate

​Clearing Browser Storage

​Troubleshooting History Issues

​Next Steps

Audio Export

Using VozCraft

Troubleshooting

Build docs developers (and LLMs) love

History Management

Overview

History Panel

Location and Display

Panel Components

History Items

Item Structure

Visual Display

Visual States

Renaming Audio

Default Naming

Rename Process

Rename Modal Details

Playback from History

Playing Audio

Duration Calculation

Deleting History Items

Delete Single Item

Clear All History

Exporting History (JSON)

Export Process

JSON File Structure

Use Cases for JSON Export

Importing History (JSON)

Import Process

Import Behavior

Valid JSON Format

History Limit and Rotation

30-Item Maximum

Managing the Limit

Browser Storage Details

Local Storage Implementation

Storage Characteristics

Storage Size Estimate

Clearing Browser Storage

Troubleshooting History Issues

Next Steps