musica-ia/als_gen/README.md

# Generador de Archivos .als (Ableton Live Set)

## Descripción

Este proyecto implementa un generador y analizador de archivos `.als` (Ableton Live Set) usando Python. Permite hacer ingeniería inversa del formato XML comprimido utilizado por Ableton Live para generar nuevos proyectos de música electrónica o modificar proyectos existentes.

## Características

### 🎵 Generación de Archivos .als
- Crear proyectos completamente nuevos desde cero
- Generar múltiples tracks (MIDI, Group, Return)
- Añadir clips MIDI con patrones de notas personalizables
- Configurar mixer, routing y efectos
- Compatible con Ableton Live 12 Suite

### 🔍 Análisis de Proyectos
- Examinar estructura completa del proyecto
- Listar tracks, clips y dispositivos
- Analizar notas MIDI y patrones
- Exportar información a archivos de texto

### ✏️ Modificación de Proyectos Existentes
- Randomizar velocidades de notas MIDI
- Transponer notas por semitonos
- Duplicar clips en diferentes tracks
- Generar variaciones automáticas
- Preservar toda la información original

## Archivos Incluidos

```
/mnt/c/als_gen/
├── als_generator.py      # Generador principal de archivos .als
├── als_analyzer.py       # Analizador y modificador
├── ejemplo_uso.py        # Script con ejemplos completos
├── README.md             # Esta documentación
├── generated_project.als # Proyecto de ejemplo generado
└── jukeblocks - Pop.als  # Proyecto original para análisis
```

## Requisitos

- Python 3.6 o superior
- Librerías estándar de Python (no requiere instalación adicional)

## Uso Básico

### 1. Generar un nuevo proyecto

```bash
python3 als_generator.py
```

Esto genera un archivo `generated_project.als` con:
- 1 GroupTrack (Drums)
- 5 tracks MIDI (Kick, Snare, HiHat, Bass, Lead)
- 8 clips MIDI con patrones de 16 notas cada uno
- Configuración completa de mixer y routing

### 2. Analizar un proyecto existente

```bash
python3 als_analyzer.py mi_proyecto.als
```

Mostrará información detallada:
- Versión de Ableton Live
- Lista de tracks y sus propiedades
- Clips MIDI y número de notas
- Tiempo de inicio de cada clip

### 3. Modificar un proyecto

#### Randomizar velocidades
```bash
python3 als_analyzer.py mi_proyecto.als randomize-vel 70 127
```
Crea `mi_proyecto_modified.als` con velocidades aleatorias entre 70-127.

#### Transponer notas
```bash
python3 als_analyzer.py mi_proyecto.als transpose 5
```
Transpone todas las notas +5 semitonos.

#### Duplicar clips
```bash
python3 als_analyzer.py mi_proyecto.als duplicate 2 4
```
Duplica clips del track 2, creando 4 copias.

#### Exportar información
```bash
python3 als_analyzer.py mi_proyecto.als export proyecto_info.txt
```
Guarda un reporte completo en archivo de texto.

### 4. Ejecutar ejemplos completos

```bash
python3 ejemplo_uso.py
```

Ejecuta una demostración completa que incluye:
- Generación de nuevos proyectos
- Análisis de proyectos existentes
- Múltiples modificaciones
- Creación de variaciones
- Resumen final con todos los archivos creados

## Programación API

### Clase ALSGenerator

```python
from als_generator import ALSGenerator

# Crear generador
generator = ALSGenerator()

# Generar proyecto completo
als_tree = generator.create_full_als(
    project_name="Mi Proyecto",
    num_tracks=5,      # Número de tracks MIDI
    num_clips=8        # Número de clips por track
)

# Guardar archivo
generator.save_als(als_tree, "mi_proyecto.als")
```

#### Métodos principales:

- `create_ableton_root()` - Crear elemento raíz Ableton
- `create_liveset_root()` - Crear LiveSet base
- `create_track(name, type, color)` - Crear track (MidiTrack/GroupTrack)
- `create_midi_clip(name, start_time, num_notes, midi_key)` - Crear clip MIDI
- `create_full_als(project_name, num_tracks, num_clips)` - Proyecto completo
- `save_als(element_tree, filename)` - Guardar archivo comprimido

### Clase ALSModificator

```python
from als_analyzer import ALSModificator

# Cargar proyecto
modificator = ALSModificator("mi_proyecto.als")
modificator.load_als()

# Modificar
modificator.randomize_velocities(60, 127)
modificator.transpose_notes(3)
modificator.duplicate_clips(1, 2)

# Guardar modificado
modificator.save_als("mi_proyecto_modificado.als")
```

#### Métodos principales:

- `load_als()` - Cargar archivo .als
- `print_project_info()` - Mostrar información completa
- `get_tracks_info()` - Obtener lista de tracks
- `get_clips_info()` - Obtener lista de clips
- `randomize_velocities(min, max)` - Randomizar velocidades
- `transpose_notes(semitones)` - Transponer notas
- `duplicate_clips(track_index, num_duplicates)` - Duplicar clips
- `save_als(output_filename)` - Guardar archivo modificado
- `export_info(output_file)` - Exportar información a texto

## Estructura Técnica

### Formato .als

Los archivos `.als` son archivos gzip que contienen un documento XML con:

```
<Ableton MajorVersion="4" MinorVersion="9.5_327" ...>
  <LiveSet>
    <Tracks>
      <GroupTrack> ... </GroupTrack>
      <MidiTrack> ... </MidiTrack>
      ...
    </Tracks>
    <Scenes> ... </Scenes>
    <MasterTrack> ... </MasterTrack>
    ...
  </LiveSet>
</Ableton>
```

### Elementos Principales

1. **LiveSet** - Contenedor principal del proyecto
2. **Tracks** - Lista de tracks (GroupTrack, MidiTrack, ReturnTrack)
3. **DeviceChain** - Cadena de dispositivos y mixer
4. **Clips** - Clips MIDI con notas y eventos
5. **MidiNoteEvent** - Eventos individuales de notas MIDI
6. **KeyTrack** - Pistas por tecla MIDI
7. **Scenes** - Escenas para Session View

### Atributos Importantes

- `LomId` - Live Object Model ID (identificador único)
- `LomIdView` - ID de vista
- `Value` - Valores numéricos (volumen, pan, etc.)
- `Manual` - Valores manuales vs automatizados
- `Id` - IDs específicos de elementos

## Ejemplos de Uso Avanzado

### Ejemplo 1: Crear un proyecto con patrón personalizado

```python
from als_generator import ALSGenerator

generator = ALSGenerator()
als_tree = generator.create_full_als("Mi Proyecto", 3, 12)

# El proyecto incluye automáticamente:
# - GroupTrack "Drums" (176)
# - 3 tracks MIDI individuales
# - 12 clips con 16 notas cada uno
# - Mixer completo con sends
# - Escenas y Master track

generator.save_als(als_tree, "mi_proyecto_personalizado.als")
```

### Ejemplo 2: Modificar proyecto existente

```python
from als_analyzer import ALSModificator

modificator = ALSModificator("jukeblocks - Pop.als")

if modificator.load_als():
    # Mostrar información
    modificator.print_project_info()

    # Randomizar con rango específico
    modificator.randomize_velocities(80, 120)

    # Transponer hacia abajo
    modificator.transpose_notes(-2)

    # Duplicar en varios tracks
    for track_idx in [1, 2, 3]:
        modificator.duplicate_clips(track_idx, 2)

    # Guardar
    modificator.save_als("jukeblocks_variacion.als")
```

### Ejemplo 3: Generar múltiples variaciones

```python
import random
from als_analyzer import ALSModificator

base_project = "proyecto_base.als"

for i in range(5):
    modificator = ALSModificator(base_project)
    modificator.load_als()

    # Variación aleatoria
    transposicion = random.choice([-5, -2, 0, 2, 5])
    modificator.transpose_notes(transposicion)

    # Randomizar con diferentes rangos
    min_vel = random.randint(60, 90)
    max_vel = random.randint(100, 127)
    modificator.randomize_velocities(min_vel, max_vel)

    # Duplicar clips
    modificator.duplicate_clips(1, random.randint(1, 3))

    output = f"variacion_{i+1}.als"
    modificator.save_als(output)
```

## Limitaciones Conocidas

1. **Tempo** - El cambio de tempo requiere análisis más profundo del XML
2. **Audio Clips** - Solo maneja clips MIDI (no audio)
3. **Dispositivos** - No modifica dispositivos VST o built-in
4. **Samples** - No incluye o modifica samples
5. **Automation** - No maneja automatización de parámetros
6. **Compression** - Solo compression gzip (no ZIP)

## Desarrollo y Extensión

Para añadir nuevas funcionalidades:

1. **Nuevos tipos de track** - Modificar `create_track()`
2. **Nuevos dispositivos** - Añadir en `_create_mixer_section()`
3. **Nuevos eventos MIDI** - Modificar `create_midi_clip()`
4. **Nuevas modificaciones** - Añadir métodos en `ALSModificator`

## Compatibilidad

- ✅ Ableton Live 9.7.7
- ✅ Ableton Live 12.0.5
- ✅ Python 3.6+
- ✅ Linux, macOS, Windows

## Pruebas

Todos los archivos generados han sido probados y pueden abrirse directamente en Ableton Live 12 Suite.

Para verificar un archivo:
```bash
python3 als_analyzer.py archivo_generado.als info
```

## Licencia

Este proyecto es de código abierto y está disponible bajo licencia MIT.

## Soporte

Para reportar bugs o solicitar funcionalidades, crear un issue en el repositorio del proyecto.

## Créditos

Desarrollado como ejemplo de ingeniería inversa del formato .als de Ableton Live.