ass-to-lrc

Name	ass-to-lrc JSON
Version	0.3.0 JSON
	download
home_page	None
Summary	Convert ASS subtitle files to LRC lyrics format with karaoke timing support
upload_time	2025-11-02 06:39:37
maintainer	None
docs_url	None
author	None
requires_python	>=3.11
license	MIT
keywords	ass converter karaoke lrc lyrics subtitle
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # ASS to LRC Converter

A Pythonic CLI application to convert ASS (Advanced SubStation Alpha) subtitle files to LRC (Lyrics) format with support
for enhanced word-level timing.

## Features

- **OOP Design**: Clean, maintainable object-oriented architecture with dedicated classes for parsing, conversion, and
  data models
- **Bidirectional Conversion**: Convert between ASS and LRC formats
- **Enhanced LRC**: Generates `.elrc` files with word-level timing from `\K` karaoke tags
- **Simple LRC**: Standard LRC format without word timing
- **Compact Format**: Merge repeated lyrics with multiple timestamps (e.g., choruses)
- **Expand Command**: Convert compact LRC back to standard sorted format
- **LRC to ASS**: Convert LRC files back to ASS format with karaoke timing support
- **Metadata Support**: Automatically extracts and converts metadata tags (artist, lyricist, album, etc.)
- **Comment Events**: Support both ASS Comment events and effect=tag for metadata
- **Effect-Based Line Breaks**: Automatically add line breaks when effect contains "break"
- **Configurable Gaps**: Add customizable gaps between lyric lines
- **Typer CLI**: Modern, user-friendly command-line interface with subcommands

## Installation

```bash
pip install -e .
```

## Usage

### Basic Usage

```bash
# Convert ASS to enhanced LRC (default)
ass2lrc convert input.ass

# Outputs: input.elrc
```

### Commands

#### `convert` - Convert ASS to LRC

Convert ASS subtitle files to LRC lyrics format.

```bash
ass2lrc convert [OPTIONS] INPUT_FILE
```

**Arguments:**

- `INPUT_FILE` - Path to input ASS file (required)

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--output` | `-o` | Output LRC file path | Same as input with `.lrc`/`.elrc` extension |
| `--enhanced` | `-e` | Generate enhanced LRC with word timing | `enabled` |
| `--simple` | `-s` | Generate simple LRC (line timing only) | `disabled` |
| `--compact` | `-c` | Use compact format (multiple timestamps per line) | `disabled` |
| `--gap` | `-g` | Gap in seconds between lines (≥0.0) | `1.0` |
| `--version` | `-v` | Show version and exit | - |
| `--help` | | Show help message | - |

**Examples:**

```bash
# Convert to enhanced LRC (default)
ass2lrc convert song.ass

# Convert to simple LRC
ass2lrc convert song.ass --simple

# Specify output file
ass2lrc convert song.ass -o lyrics.lrc

# Custom line gap (0.5 seconds)
ass2lrc convert song.ass --gap 0.5

# Compact format for repeated lyrics
ass2lrc convert song.ass --compact

# Enhanced LRC with custom gap
ass2lrc convert song.ass -e -g 0.8 -o song.elrc

# Simple LRC with no gap
ass2lrc convert song.ass -s -g 0
```

#### `expand` - Expand Compact LRC

Expand compact LRC format to standard sorted format.

```bash
ass2lrc expand [OPTIONS] INPUT_FILE
```

**Arguments:**

- `INPUT_FILE` - Path to input compact LRC file (required)

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--output` | `-o` | Output expanded LRC file path | Input with `_expanded` suffix |
| `--help` | | Show help message | - |

**Examples:**

```bash
# Expand compact LRC to standard format
ass2lrc expand compact.lrc

# Specify output file
ass2lrc expand compact.lrc -o expanded.lrc
```

#### `lrc2ass` - Convert LRC to ASS

Convert LRC lyrics files back to ASS subtitle format.

```bash
ass2lrc lrc2ass [OPTIONS] INPUT_FILE
```

**Arguments:**

- `INPUT_FILE` - Path to input LRC file (required)

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--output` | `-o` | Output ASS file path | Same as input with `.ass` extension |
| `--karaoke` | `-k` | Generate karaoke timing tags from enhanced LRC | `enabled` |
| `--no-karaoke` | `-K` | Disable karaoke tags (plain text only) | `disabled` |
| `--help` | | Show help message | - |

**Examples:**

```bash
# Convert enhanced LRC to ASS with karaoke tags
ass2lrc lrc2ass song.elrc

# Convert simple LRC to ASS without karaoke
ass2lrc lrc2ass song.lrc --no-karaoke

# Specify output file
ass2lrc lrc2ass lyrics.lrc -o subtitles.ass
```

### Global Options

```bash
# Show version
ass2lrc --version

# Show help
ass2lrc --help

# Show help for specific command
ass2lrc convert --help
ass2lrc expand --help
ass2lrc lrc2ass --help
```

## ASS Format Requirements

### Metadata Tags

Include metadata using Comment events or Dialogue lines with `effect=tag`:

#### Method 1: Comment events (recommended)

```ass
Comment: 0,0:00:00.00,0:00:00.00,Default,ti,0,0,0,,Song Title
Comment: 0,0:00:00.00,0:00:00.00,Default,ar,0,0,0,,Artist Name
Comment: 0,0:00:00.00,0:00:00.00,Default,lr,0,0,0,,Lyricist Name
```

#### Method 2: Dialogue with effect=tag

```ass
Dialogue: 0,0:00:00.00,0:00:02.00,Default,ti,0,0,0,tag,Song Title
Dialogue: 0,0:00:00.00,0:00:02.00,Default,ar,0,0,0,tag,Artist Name
Dialogue: 0,0:00:00.00,0:00:02.00,Default,lr,0,0,0,tag,Lyricist Name
```

Supported metadata tags (following LRC specification):

- `ti`: Title of the song
- `ar`: Artist performing the song
- `al`: Album the song is from
- `au`: Author of the song
- `lr`: Lyricist of the song
- `length`: Length of the song (mm:ss)
- `by`: Author of the LRC file (not the song)
- `offset`: Global offset value for lyric times in milliseconds (e.g., +100 or -50)
- `re` / `tool`: The player or editor that created the LRC file
- `ve`: The version of the program
- `#`: Comments (can have multiple)

### Karaoke Timing

Use `\K` or `\k` tags for syllable timing (in centiseconds):

```ass
Dialogue: 0,0:00:00.62,0:00:07.52,Default,,0,0,0,,{\K72}Text{\K106}Here
```

### Effect-Based Line Breaks

Lines with an effect field containing "break" (case-insensitive) will automatically add an empty line after them in the LRC output:

```ass
Dialogue: 0,0:00:10.00,0:00:12.00,Default,,0,0,0,linebreak,First verse
Dialogue: 0,0:00:13.00,0:00:15.00,Default,,0,0,0,,Second verse
```

This will produce:

```lrc
[00:10.00]First verse
[00:12.00]
[00:13.00]Second verse
```

## Compact Format

The compact format merges identical lyrics that appear at different times into a single line with multiple timestamps.
This is useful for repeated sections like choruses.

**Example:**

```lrc
Standard format:
[00:10.00]Chorus line here
[00:30.00]Chorus line here
[00:50.00]Chorus line here

Compact format:
[00:10.00][00:30.00][00:50.00]Chorus line here
```

> [!WARNING]
>
> - Not all LRC players support the compact format. Use the `expand` command to convert back to standard format if needed.
> - **Compact format doesn't support word timing**. If you use `--compact` with `--enhanced`, word timing will be
>   automatically disabled and a compact LRC without word timing will be generated.

## Architecture

The application is structured using OOP principles:

- **`models.py`**: Data classes for `Syllable`, `LyricLine`, and `Metadata`
- **`parser.py`**: `ASSParser` class for parsing ASS files
- **`lrc_parser.py`**: `LRCParser` class for parsing LRC files
- **`converter.py`**: `LRCConverter` class for generating LRC output
- **`ass_converter.py`**: `ASSConverter` class for generating ASS output
- **`expander.py`**: `LRCExpander` class for expanding compact format
- **`cli.py`**: Typer-based command-line interface

## Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_parser.py -v

# Run with coverage
pytest tests/ --cov=ass2lrc --cov-report=term-missing
```

### Code Quality

```bash
# Lint with ruff
task lint

# Format code
task format

# Type check
task typecheck

# Run all checks
task qa
```

### Using Task

Available commands:

```bash
task                 # Show all available tasks
task install         # Install package
task install-dev     # Install with dev dependencies
task test            # Run tests
task test-cov        # Run tests with coverage
task lint            # Run linter
task format          # Format code
task typecheck       # Type checking
task qa              # Run all quality checks
task clean           # Remove generated files
task build           # Build distribution packages
task publish-test    # Publish to TestPyPI
task publish         # Publish to PyPI
```

Install Task from: <https://taskfile.dev/installation/>

## License

See LICENSE file for details.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Quick Start

```bash
# Clone repository
git clone https://github.com/nattadasu/ass-to-lrc.git
cd ass-to-lrc

# Setup development environment (uses uv)
task dev

# Make changes and test
task qa
```

### Commit Convention

This project follows [Conventional Commits](https://www.conventionalcommits.org/).

**Format**: `<type>(<scope>): <subject>`

**Example**: `feat(converter): Add compact LRC format support`

Pre-commit hooks will automatically validate your commits. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "ass-to-lrc",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "ass, converter, karaoke, lrc, lyrics, subtitle",
    "author": null,
    "author_email": "Natsu Tadama <nattadasu@nattadasu.my.id>",
    "download_url": "https://files.pythonhosted.org/packages/67/c5/0c6bfe5867482608969a5fad54d0e3c589981136bb8244a3de6ac1cfbc13/ass_to_lrc-0.3.0.tar.gz",
    "platform": null,
    "description": "# ASS to LRC Converter\n\nA Pythonic CLI application to convert ASS (Advanced SubStation Alpha) subtitle files to LRC (Lyrics) format with support\nfor enhanced word-level timing.\n\n## Features\n\n- **OOP Design**: Clean, maintainable object-oriented architecture with dedicated classes for parsing, conversion, and\n  data models\n- **Bidirectional Conversion**: Convert between ASS and LRC formats\n- **Enhanced LRC**: Generates `.elrc` files with word-level timing from `\\K` karaoke tags\n- **Simple LRC**: Standard LRC format without word timing\n- **Compact Format**: Merge repeated lyrics with multiple timestamps (e.g., choruses)\n- **Expand Command**: Convert compact LRC back to standard sorted format\n- **LRC to ASS**: Convert LRC files back to ASS format with karaoke timing support\n- **Metadata Support**: Automatically extracts and converts metadata tags (artist, lyricist, album, etc.)\n- **Comment Events**: Support both ASS Comment events and effect=tag for metadata\n- **Effect-Based Line Breaks**: Automatically add line breaks when effect contains \"break\"\n- **Configurable Gaps**: Add customizable gaps between lyric lines\n- **Typer CLI**: Modern, user-friendly command-line interface with subcommands\n\n## Installation\n\n```bash\npip install -e .\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Convert ASS to enhanced LRC (default)\nass2lrc convert input.ass\n\n# Outputs: input.elrc\n```\n\n### Commands\n\n#### `convert` - Convert ASS to LRC\n\nConvert ASS subtitle files to LRC lyrics format.\n\n```bash\nass2lrc convert [OPTIONS] INPUT_FILE\n```\n\n**Arguments:**\n\n- `INPUT_FILE` - Path to input ASS file (required)\n\n**Options:**\n\n| Option | Short | Description | Default |\n|--------|-------|-------------|---------|\n| `--output` | `-o` | Output LRC file path | Same as input with `.lrc`/`.elrc` extension |\n| `--enhanced` | `-e` | Generate enhanced LRC with word timing | `enabled` |\n| `--simple` | `-s` | Generate simple LRC (line timing only) | `disabled` |\n| `--compact` | `-c` | Use compact format (multiple timestamps per line) | `disabled` |\n| `--gap` | `-g` | Gap in seconds between lines (\u22650.0) | `1.0` |\n| `--version` | `-v` | Show version and exit | - |\n| `--help` | | Show help message | - |\n\n**Examples:**\n\n```bash\n# Convert to enhanced LRC (default)\nass2lrc convert song.ass\n\n# Convert to simple LRC\nass2lrc convert song.ass --simple\n\n# Specify output file\nass2lrc convert song.ass -o lyrics.lrc\n\n# Custom line gap (0.5 seconds)\nass2lrc convert song.ass --gap 0.5\n\n# Compact format for repeated lyrics\nass2lrc convert song.ass --compact\n\n# Enhanced LRC with custom gap\nass2lrc convert song.ass -e -g 0.8 -o song.elrc\n\n# Simple LRC with no gap\nass2lrc convert song.ass -s -g 0\n```\n\n#### `expand` - Expand Compact LRC\n\nExpand compact LRC format to standard sorted format.\n\n```bash\nass2lrc expand [OPTIONS] INPUT_FILE\n```\n\n**Arguments:**\n\n- `INPUT_FILE` - Path to input compact LRC file (required)\n\n**Options:**\n\n| Option | Short | Description | Default |\n|--------|-------|-------------|---------|\n| `--output` | `-o` | Output expanded LRC file path | Input with `_expanded` suffix |\n| `--help` | | Show help message | - |\n\n**Examples:**\n\n```bash\n# Expand compact LRC to standard format\nass2lrc expand compact.lrc\n\n# Specify output file\nass2lrc expand compact.lrc -o expanded.lrc\n```\n\n#### `lrc2ass` - Convert LRC to ASS\n\nConvert LRC lyrics files back to ASS subtitle format.\n\n```bash\nass2lrc lrc2ass [OPTIONS] INPUT_FILE\n```\n\n**Arguments:**\n\n- `INPUT_FILE` - Path to input LRC file (required)\n\n**Options:**\n\n| Option | Short | Description | Default |\n|--------|-------|-------------|---------|\n| `--output` | `-o` | Output ASS file path | Same as input with `.ass` extension |\n| `--karaoke` | `-k` | Generate karaoke timing tags from enhanced LRC | `enabled` |\n| `--no-karaoke` | `-K` | Disable karaoke tags (plain text only) | `disabled` |\n| `--help` | | Show help message | - |\n\n**Examples:**\n\n```bash\n# Convert enhanced LRC to ASS with karaoke tags\nass2lrc lrc2ass song.elrc\n\n# Convert simple LRC to ASS without karaoke\nass2lrc lrc2ass song.lrc --no-karaoke\n\n# Specify output file\nass2lrc lrc2ass lyrics.lrc -o subtitles.ass\n```\n\n### Global Options\n\n```bash\n# Show version\nass2lrc --version\n\n# Show help\nass2lrc --help\n\n# Show help for specific command\nass2lrc convert --help\nass2lrc expand --help\nass2lrc lrc2ass --help\n```\n\n## ASS Format Requirements\n\n### Metadata Tags\n\nInclude metadata using Comment events or Dialogue lines with `effect=tag`:\n\n#### Method 1: Comment events (recommended)\n\n```ass\nComment: 0,0:00:00.00,0:00:00.00,Default,ti,0,0,0,,Song Title\nComment: 0,0:00:00.00,0:00:00.00,Default,ar,0,0,0,,Artist Name\nComment: 0,0:00:00.00,0:00:00.00,Default,lr,0,0,0,,Lyricist Name\n```\n\n#### Method 2: Dialogue with effect=tag\n\n```ass\nDialogue: 0,0:00:00.00,0:00:02.00,Default,ti,0,0,0,tag,Song Title\nDialogue: 0,0:00:00.00,0:00:02.00,Default,ar,0,0,0,tag,Artist Name\nDialogue: 0,0:00:00.00,0:00:02.00,Default,lr,0,0,0,tag,Lyricist Name\n```\n\nSupported metadata tags (following LRC specification):\n\n- `ti`: Title of the song\n- `ar`: Artist performing the song\n- `al`: Album the song is from\n- `au`: Author of the song\n- `lr`: Lyricist of the song\n- `length`: Length of the song (mm:ss)\n- `by`: Author of the LRC file (not the song)\n- `offset`: Global offset value for lyric times in milliseconds (e.g., +100 or -50)\n- `re` / `tool`: The player or editor that created the LRC file\n- `ve`: The version of the program\n- `#`: Comments (can have multiple)\n\n### Karaoke Timing\n\nUse `\\K` or `\\k` tags for syllable timing (in centiseconds):\n\n```ass\nDialogue: 0,0:00:00.62,0:00:07.52,Default,,0,0,0,,{\\K72}Text{\\K106}Here\n```\n\n### Effect-Based Line Breaks\n\nLines with an effect field containing \"break\" (case-insensitive) will automatically add an empty line after them in the LRC output:\n\n```ass\nDialogue: 0,0:00:10.00,0:00:12.00,Default,,0,0,0,linebreak,First verse\nDialogue: 0,0:00:13.00,0:00:15.00,Default,,0,0,0,,Second verse\n```\n\nThis will produce:\n\n```lrc\n[00:10.00]First verse\n[00:12.00]\n[00:13.00]Second verse\n```\n\n## Compact Format\n\nThe compact format merges identical lyrics that appear at different times into a single line with multiple timestamps.\nThis is useful for repeated sections like choruses.\n\n**Example:**\n\n```lrc\nStandard format:\n[00:10.00]Chorus line here\n[00:30.00]Chorus line here\n[00:50.00]Chorus line here\n\nCompact format:\n[00:10.00][00:30.00][00:50.00]Chorus line here\n```\n\n> [!WARNING]\n>\n> - Not all LRC players support the compact format. Use the `expand` command to convert back to standard format if needed.\n> - **Compact format doesn't support word timing**. If you use `--compact` with `--enhanced`, word timing will be\n>   automatically disabled and a compact LRC without word timing will be generated.\n\n## Architecture\n\nThe application is structured using OOP principles:\n\n- **`models.py`**: Data classes for `Syllable`, `LyricLine`, and `Metadata`\n- **`parser.py`**: `ASSParser` class for parsing ASS files\n- **`lrc_parser.py`**: `LRCParser` class for parsing LRC files\n- **`converter.py`**: `LRCConverter` class for generating LRC output\n- **`ass_converter.py`**: `ASSConverter` class for generating ASS output\n- **`expander.py`**: `LRCExpander` class for expanding compact format\n- **`cli.py`**: Typer-based command-line interface\n\n## Development\n\n### Running Tests\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run all tests\npytest tests/ -v\n\n# Run specific test file\npytest tests/test_parser.py -v\n\n# Run with coverage\npytest tests/ --cov=ass2lrc --cov-report=term-missing\n```\n\n### Code Quality\n\n```bash\n# Lint with ruff\ntask lint\n\n# Format code\ntask format\n\n# Type check\ntask typecheck\n\n# Run all checks\ntask qa\n```\n\n### Using Task\n\nAvailable commands:\n\n```bash\ntask                 # Show all available tasks\ntask install         # Install package\ntask install-dev     # Install with dev dependencies\ntask test            # Run tests\ntask test-cov        # Run tests with coverage\ntask lint            # Run linter\ntask format          # Format code\ntask typecheck       # Type checking\ntask qa              # Run all quality checks\ntask clean           # Remove generated files\ntask build           # Build distribution packages\ntask publish-test    # Publish to TestPyPI\ntask publish         # Publish to PyPI\n```\n\nInstall Task from: <https://taskfile.dev/installation/>\n\n## License\n\nSee LICENSE file for details.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n### Quick Start\n\n```bash\n# Clone repository\ngit clone https://github.com/nattadasu/ass-to-lrc.git\ncd ass-to-lrc\n\n# Setup development environment (uses uv)\ntask dev\n\n# Make changes and test\ntask qa\n```\n\n### Commit Convention\n\nThis project follows [Conventional Commits](https://www.conventionalcommits.org/).\n\n**Format**: `<type>(<scope>): <subject>`\n\n**Example**: `feat(converter): Add compact LRC format support`\n\nPre-commit hooks will automatically validate your commits. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Convert ASS subtitle files to LRC lyrics format with karaoke timing support",
    "version": "0.3.0",
    "project_urls": {
        "Documentation": "https://github.com/nattadasu/ass-to-lrc#readme",
        "Homepage": "https://github.com/nattadasu/ass-to-lrc",
        "Issues": "https://github.com/nattadasu/ass-to-lrc/issues",
        "Repository": "https://github.com/nattadasu/ass-to-lrc"
    },
    "split_keywords": [
        "ass",
        " converter",
        " karaoke",
        " lrc",
        " lyrics",
        " subtitle"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5bfc308d3cecc208f12179459a59c2af6062acca83ac089f70b623d1791d4ba1",
                "md5": "5fe241c507c5528a9b02d19de9bb5b91",
                "sha256": "d52a1d1f1c7455980bf06e74c3f192b822a30eb5ffd356194de24d03f89ffb10"
            },
            "downloads": -1,
            "filename": "ass_to_lrc-0.3.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5fe241c507c5528a9b02d19de9bb5b91",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 16081,
            "upload_time": "2025-11-02T06:39:35",
            "upload_time_iso_8601": "2025-11-02T06:39:35.901580Z",
            "url": "https://files.pythonhosted.org/packages/5b/fc/308d3cecc208f12179459a59c2af6062acca83ac089f70b623d1791d4ba1/ass_to_lrc-0.3.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "67c50c6bfe5867482608969a5fad54d0e3c589981136bb8244a3de6ac1cfbc13",
                "md5": "2e35823939a63a0c1d46f1c6eff884ae",
                "sha256": "f27e9a40c7c43fcb8da2a4de490ac653d853671873acd7856ca68b0248e63e37"
            },
            "downloads": -1,
            "filename": "ass_to_lrc-0.3.0.tar.gz",
            "has_sig": false,
            "md5_digest": "2e35823939a63a0c1d46f1c6eff884ae",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 61325,
            "upload_time": "2025-11-02T06:39:37",
            "upload_time_iso_8601": "2025-11-02T06:39:37.541355Z",
            "url": "https://files.pythonhosted.org/packages/67/c5/0c6bfe5867482608969a5fad54d0e3c589981136bb8244a3de6ac1cfbc13/ass_to_lrc-0.3.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-11-02 06:39:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "nattadasu",
    "github_project": "ass-to-lrc#readme",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "ass-to-lrc"
}