### Install Dawtool using Pip

Source: https://github.com/offlinemark/dawtool/blob/master/README.md

Install dawtool directly from its GitHub repository using pip. This command requires Python 3.7 or greater.

```bash
pip install git+https://github.com/offlinemark/dawtool
```

--------------------------------

### Load a project for full inspection

Source: https://context7.com/offlinemark/dawtool/llms.txt

Use `load_project` to get a project object without immediate parsing. Call `.parse()` to populate markers and tempo events. `theoretical=True` skips DAW-specific tempo quantization.

```python
import dawtool
from dawtool.project import UnknownExtension

filename = 'set-with-automation.als'
with open(filename, 'rb') as f:
    proj = dawtool.load_project(filename, f)
    proj.parse()

print(repr(proj))
# <AbletonProject set-with-automation.als>

print("BPM:", proj.beats_per_min)
# BPM: 120.0

print("Has tempo automation:", proj.has_tempo_automation)
# Has tempo automation: True

for event in proj.tempo_automation_events:
    print(f"  beat={event.beat:.2f}  bpm={event.bpm:.2f}  real_time={event.real_time}")
# beat=-63072000.00  bpm=60.00  real_time=0.0
# beat=4.00  bpm=60.00  real_time=4.0
# beat=8.00  bpm=120.00  real_time=6.77

for marker in proj.markers:
    print(f"  {marker.time:.3f}s  '{marker.text}'")
# 0.000s  'A'
# 4.000s  'B'
# 6.773s  'C'
```

--------------------------------

### dawtool.load_project

Source: https://context7.com/offlinemark/dawtool/llms.txt

Loads and returns a format-specific project object without parsing. Call .parse() to trigger parsing and populate .markers and .tempo_automation_events.

```APIDOC
## dawtool.load_project(filename, stream, theoretical=False)

### Description
Loads a DAW project for full inspection.

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the DAW project file.
- **stream** (file-like object) - Required - A readable binary stream of the DAW project file.
#### Query Parameters
- **theoretical** (boolean) - Optional - If True, skips DAW-specific tempo quantization and uses numerical integration.

### Request Example
```python
import dawtool
from dawtool.project import UnknownExtension

filename = 'set-with-automation.als'
with open(filename, 'rb') as f:
    proj = dawtool.load_project(filename, f)
    proj.parse()

print(repr(proj))
print("BPM:", proj.beats_per_min)
print("Has tempo automation:", proj.has_tempo_automation)

for event in proj.tempo_automation_events:
    print(f"  beat={event.beat:.2f}  bpm={event.bpm:.2f}  real_time={event.real_time}")

for marker in proj.markers:
    print(f"  {marker.time:.3f}s  '{marker.text}'")
```

### Response
#### Success Response (Project object)
- **beats_per_min** (float) - The beats per minute of the project.
- **has_tempo_automation** (boolean) - Indicates if the project has tempo automation.
- **tempo_automation_events** (list) - A list of tempo automation events.
- **markers** (list) - A list of Marker objects.

#### Response Example
```
<AbletonProject set-with-automation.als>
BPM: 120.0
Has tempo automation: True
  beat=-63072000.00  bpm=60.00  real_time=0.0
  beat=4.00  bpm=60.00  real_time=4.0
  beat=8.00  bpm=120.00  real_time=6.77
  0.000s  'A'
  4.000s  'B'
  6.773s  'C'
```
```

--------------------------------

### Parse FL Studio Project

Source: https://context7.com/offlinemark/dawtool/llms.txt

Load and parse an FL Studio project file (.flp). Access project representation, tempo automation events, and markers. Note that only non-action markers (time signature/loop) are returned.

```python
from dawtool import load_project
from dawtool.daw.flstudio import FlStudioProject

fname = 'project.flp'
with open(fname, 'rb') as f:
    proj: FlStudioProject = load_project(fname, f)
    proj.parse()

print(repr(proj))
# <FlStudioProject version=20 ppb=96 bpm=140.0 channels=12>

print("Has tempo automation:", proj.has_tempo_automation)

for event in proj.tempo_automation_events:
    print(f"  beat={event.beat:.3f}  bpm={event.bpm:.2f}")

for marker in proj.markers:
    print(f"  {marker.time:.3f}s  '{marker.text}'")
# Only NONE-action markers are returned (time signature / loop
# markers are automatically filtered out)
```

--------------------------------

### Advanced Python API (Markers & Other Data)

Source: https://github.com/offlinemark/dawtool/blob/master/README.md

This API provides access to a wider range of data within the DAW project, including markers, tempo automation, and more. It loads the project, parses it, and allows access to various project attributes.

```APIDOC
## Advanced Python API (Markers & Other Data)

### Description
Loads, parses, and extracts comprehensive data from a DAW project file.

### Usage
```python
import sys
import dawtool

filename = sys.argv[1]
with open(filename, 'rb') as f:
    # Load project based on file extension
    proj = dawtool.load_project(filename, f)
    # Parse project, recompute time markers
    proj.parse()
    # Access project data
    for marker in proj.markers:
        print(marker.time, marker.text)
```

### Methods
- `dawtool.load_project(filename, file_object)`: Loads the project file based on its extension.
- `proj.parse()`: Parses the loaded project data.

### Accessing Data
- `proj.markers`: A list of marker objects.

### Parameters
- `filename` (string): The path to the DAW project file.
- `file_object` (file object): An opened file object in binary read mode (`'rb'`).

### Returns
A project object (`proj`) with various attributes, including `markers`.
```

--------------------------------

### Parse Ableton Live Project

Source: https://context7.com/offlinemark/dawtool/llms.txt

Load and parse an Ableton Live project file (.als). Access project version, raw markers, tempo automation, and computed markers. Use `proj.dump()` for a verbose timeline.

```python
from dawtool import load_project
from dawtool.daw.ableton import AbletonProject, TempoAutomationFloatEvent

fname = 'project.als'
with open(fname, 'rb') as f:
    proj: AbletonProject = load_project(fname, f)
    proj.parse()

# Version info
v = proj.version
print(f"Created by: {v.creator}")   # Ableton Live 10.1.7
print(f"Major: {v.major}, Minor: {v.minorA}")  # Major: 5, Minor: 10

# Raw markers (beat positions, not seconds)
for rm in proj.raw_markers:
    print(f"  beat={rm.beat}  text='{rm.text}'")

# Tempo automation events (beat → real-time mapping)
for ev in proj.tempo_automation_events:
    if isinstance(ev, TempoAutomationFloatEvent):
        print(f"  beat={ev.beat:.3f}  bpm={ev.bpm:.3f}  real={ev.real_time:.3f}s")

# Final computed markers (seconds)
for m in proj.markers:
    print(f"  {m.time:.3f}s  {m.text}")

# Verbose timeline dump to stdout
proj.dump()
```

--------------------------------

### Extract Time Markers from File (CLI)

Source: https://context7.com/offlinemark/dawtool/llms.txt

Use the `dawtool` command-line interface to extract time markers from supported audio files. Options include specifying output format (long hours) and using theoretical time calculation.

```bash
# Extract time markers from any supported file
dawtool -m my-dj-mix.als
# 00:00.000 nciku - peaceofmind
# 02:15.115 comfort - a n g e l _ w i n g s
# 05:18.654 rose bride rings - femme fatale

# Hours format
dawtool -m -x long-mix.als
# 0:00:00 Track 1
# 1:02:15 Track 2

# Use theoretical (non-DAW-quantized) time calculation
dawtool -m -t project.als

# Verbose: dump full automation timeline
dawtool -m -v project.als

# Re-emit cue file (corrects rekordbox timestamps)
dawtool -e tracklist.cue > fixed.cue

# Debug logging
dawtool -d -m project.als
```

--------------------------------

### Extract Markers via Command Line Tool

Source: https://github.com/offlinemark/dawtool/blob/master/README.md

Use the dawtool command-line interface to quickly extract and display time markers from a specified DAW file. The '-m' flag indicates marker extraction.

```bash
$ dawtool -m my-dj-mix.als
00:00.000 nciku - peaceofmind
02:15.115 comfort - a n g e l _ w i n g s
05:18.654 rose bride rings - femme fatale
06:52.654 ranov - butterfly
08:47.077 scalade - tempura VIP
10:57.423 mirvs - defrosted
```

--------------------------------

### Simple Python API (Markers Only)

Source: https://github.com/offlinemark/dawtool/blob/master/README.md

This API extracts only the time markers from a DAW file. It's suitable for use cases where only marker data is needed.

```APIDOC
## Simple Python API (Markers Only)

### Description
Extracts time markers from a DAW file.

### Usage
```python
import sys
import dawtool

filename = sys.argv[1]
with open(filename, 'rb') as f:
    markers = dawtool.extract_markers(filename, f)
    for marker in markers:
        print(marker.time, marker.text)
```

### Parameters
- `filename` (string): The path to the DAW project file.
- `f` (file object): An opened file object in binary read mode (`'rb'`).

### Returns
A list of marker objects, where each marker has `time` and `text` attributes.
```

--------------------------------

### Command Line Tool

Source: https://github.com/offlinemark/dawtool/blob/master/README.md

The command-line interface allows users to extract time markers directly from the terminal.

```APIDOC
## Command Line Tool

### Description
Extracts time markers from DAW files using the command line.

### Usage
```bash
$ dawtool -m my-dj-mix.als
```

### Options
- `-m`: Specifies that time markers should be extracted and displayed.
```

--------------------------------

### Extract markers from a DAW file

Source: https://context7.com/offlinemark/dawtool/llms.txt

Use `extract_markers` to load and parse a project file, returning a list of `Marker` objects sorted by time. Handles `FileNotFoundError`, `UnknownExtension`, and `ValueError`.

```python
import dawtool
from dawtool.project import UnknownExtension

filename = 'my-dj-mix.als'
try:
    with open(filename, 'rb') as f:
        markers = dawtool.extract_markers(filename, f)
    for marker in markers:
        print(f"{marker.time:.3f}s  {marker.text}")
        # Output: 0.000s  nciku - peaceofmind
        #         135.115s  comfort - a n g e l _ w i n g s
except FileNotFoundError:
    print(f"File not found: {filename}")
except UnknownExtension as e:
    print(f"Unsupported file type: {e}")
except ValueError as e:
    print(f"Could not parse file: {e}")
```

--------------------------------

### Extract Time Markers with Python API

Source: https://github.com/offlinemark/dawtool/blob/master/README.md

Use this simple API to extract only time markers from a DAW file. Ensure the file is opened in binary read mode.

```python
import sys
import dawtool

filename = sys.argv[1]
with open(filename, 'rb') as f:
    markers = dawtool.extract_markers(filename, f)
    for marker in markers:
        print(marker.time, marker.text)
```

--------------------------------

### Parse and Emit Cue Sheet

Source: https://context7.com/offlinemark/dawtool/llms.txt

Load and parse a Cue sheet file (.cue). Access performer, title, file information, and markers. The `.emit()` method can re-emit a corrected cue file, fixing rekordbox-specific INDEX timestamps.

```python
from dawtool import load_project
from dawtool.daw.cue import CueFile

fname = 'tracklist.cue'
with open(fname, 'rb') as f:
    proj: CueFile = load_project(fname, f)
    proj.parse()

print(f"Performer: {proj.performer}")
print(f"Title:     {proj.title}")
print(f"File:      {proj.file} [{proj.file_type}]")
print(f"rekordbox: {proj._from_rekordbox}")

for i, m in enumerate(proj.markers, 1):
    mins = int(m.time // 60)
    secs = int(m.time % 60)
    print(f"  Track {i:02}: {mins:02}:{secs:02}  {m.text}")
    # Track 01: 00:00  Artist A - Song Title
    # Track 02: 04:32  Artist B - Another Song

# Re-emit a corrected cue file (fixes rekordbox INDEX times)
with open('fixed.cue', 'w') as out:
    out.write(proj.emit())
```

--------------------------------

### Advanced Data Extraction with Python API

Source: https://github.com/offlinemark/dawtool/blob/master/README.md

Utilize the advanced API to load a project, parse it, and access various data including time markers and tempo automation. The project is loaded based on the file extension.

```python
import sys
import dawtool

filename = sys.argv[1]
with open(filename, 'rb') as f:
    # Load project based on file extension
    proj = dawtool.load_project(filename, f)
    # Parse project, recompute time markers
    proj.parse()
    # Access project data
    for marker in proj.markers:
        print(marker.time, marker.text)
```

--------------------------------

### dawtool.extract_markers

Source: https://context7.com/offlinemark/dawtool/llms.txt

Convenience function that loads and parses a project file, returning a list of Marker objects sorted by time. Raises ValueError for malformed files and UnknownExtension for unsupported file types.

```APIDOC
## dawtool.extract_markers(filename, stream, theoretical=False)

### Description
Extracts time markers from a DAW file.

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the DAW project file.
- **stream** (file-like object) - Required - A readable binary stream of the DAW project file.
#### Query Parameters
- **theoretical** (boolean) - Optional - If True, skips DAW-specific tempo quantization.

### Request Example
```python
import dawtool
from dawtool.project import UnknownExtension

filename = 'my-dj-mix.als'
try:
    with open(filename, 'rb') as f:
        markers = dawtool.extract_markers(filename, f)
    for marker in markers:
        print(f"{marker.time:.3f}s  {marker.text}")
except FileNotFoundError:
    print(f"File not found: {filename}")
except UnknownExtension as e:
    print(f"Unsupported file type: {e}")
except ValueError as e:
    print(f"Could not parse file: {e}")
```

### Response
#### Success Response (list of Marker objects)
- **time** (float) - The real wall-clock time in seconds.
- **text** (string) - The annotation string from the DAW project.

#### Response Example
```
0.000s  nciku - peaceofmind
135.115s  comfort - a n g e l _ w i n g s
```
```

--------------------------------

### Format seconds as a timestamp string

Source: https://context7.com/offlinemark/dawtool/llms.txt

Use `format_time` to convert seconds into MM:SS or HH:MM:SS formats. Supports sub-second precision and optional hour padding.

```python
from dawtool import format_time

# Default: MM:SS
print(format_time(0))           # '00:00'
print(format_time(135.115))     # '02:15'
print(format_time(3620.5))      # '60:20'

# Precise: MM:SS.mmm
print(format_time(135.115, precise=True))   # '02:15.115'
print(format_time(59.1, precise=True))      # '00:59.100'

# Force hours output: HH:MM:SS
print(format_time(3661, hours_fmt=True))                  # '01:01:01'
print(format_time(3661, hours_fmt=True, hours_pad=False)) # '1:01:01'

# Real-world usage: print all markers in a DJ mix
markers = [...]  # from extract_markers(...)
for m in markers:
    print(format_time(m.time, precise=True), m.text)
# 00:00.000 nciku - peaceofmind
# 02:15.115 comfort - a n g e l _ w i n g s
# 05:18.654 rose bride rings - femme fatale
```

--------------------------------

### Marker data class

Source: https://context7.com/offlinemark/dawtool/llms.txt

The `Marker` dataclass represents a time marker with `.time` (seconds) and `.text` (annotation). `.real_time` is an alias for `.time`. Markers from `extract_markers` are sorted by time.

```python
from dawtool.marker import Marker

m = Marker(time=135.115, text='comfort - a n g e l _ w i n g s')
print(m.time)       # 135.115
print(m.text)       # comfort - a n g e l _ w i n g s
print(m.real_time)  # 135.115  (alias for .time)

# Markers from extract_markers() are sorted by time
import dawtool
with open('mix.als', 'rb') as f:
    markers = dawtool.extract_markers('mix.als', f)

assert markers == sorted(markers, key=lambda m: m.time)
```

--------------------------------

### dawtool.format_time

Source: https://context7.com/offlinemark/dawtool/llms.txt

Converts a float number of seconds into a human-readable timestamp string. Supports MM:SS and HH:MM:SS formats, optional sub-second precision, and optional hour field padding.

```APIDOC
## dawtool.format_time(total_seconds, hours_fmt=False, precise=False, hours_pad=True)

### Description
Formats seconds into a timestamp string.

### Parameters
#### Path Parameters
- **total_seconds** (float) - Required - The total number of seconds to format.
#### Query Parameters
- **hours_fmt** (boolean) - Optional - If True, formats the time in HH:MM:SS format.
- **precise** (boolean) - Optional - If True, includes sub-second precision.
- **hours_pad** (boolean) - Optional - If True and hours_fmt is True, pads the hour field.

### Request Example
```python
from dawtool import format_time

# Default: MM:SS
print(format_time(0))
print(format_time(135.115))
print(format_time(3620.5))

# Precise: MM:SS.mmm
print(format_time(135.115, precise=True))
print(format_time(59.1, precise=True))

# Force hours output: HH:MM:SS
print(format_time(3661, hours_fmt=True))
print(format_time(3661, hours_fmt=True, hours_pad=False))

# Real-world usage: print all markers in a DJ mix
markers = [...]  # from extract_markers(...)
for m in markers:
    print(format_time(m.time, precise=True), m.text)
```

### Response
#### Success Response (string)
- **formatted_time** (string) - The timestamp string.

#### Response Example
```
00:00
02:15
60:20
02:15.115
00:59.100
01:01:01
1:01:01
00:00.000 nciku - peaceofmind
02:15.115 comfort - a n g e l _ w i n g s
05:18.654 rose bride rings - femme fatale
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.