{"id":34107306,"url":"https://github.com/nattadasu/ass-to-lrc","last_synced_at":"2026-04-10T10:32:13.804Z","repository":{"id":321558512,"uuid":"1086215281","full_name":"nattadasu/ass-to-lrc","owner":"nattadasu","description":"A Pythonic CLI application to convert ASS (Advanced SubStation Alpha) subtitle files to LRC (Lyrics) format with support for enhanced word-level timing","archived":false,"fork":false,"pushed_at":"2026-04-09T01:18:34.000Z","size":106,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T03:22:36.086Z","etag":null,"topics":["lrc","lyric-parser","substation-alpha","subtitle-conversion"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nattadasu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"nattadasu","ko_fi":"nattadasu","patreon":"nattadasu","custom":["https://paypal.me/nattadasu","https://trakteer.id/nattadasu","https://saweria.co/nattadasu"]}},"created_at":"2025-10-30T05:29:24.000Z","updated_at":"2026-04-09T01:18:40.000Z","dependencies_parsed_at":"2025-10-30T10:08:23.744Z","dependency_job_id":"411c12b5-19c4-49c9-b1d9-70eab82ee70a","html_url":"https://github.com/nattadasu/ass-to-lrc","commit_stats":null,"previous_names":["nattadasu/ass-to-lrc"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nattadasu/ass-to-lrc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nattadasu%2Fass-to-lrc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nattadasu%2Fass-to-lrc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nattadasu%2Fass-to-lrc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nattadasu%2Fass-to-lrc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nattadasu","download_url":"https://codeload.github.com/nattadasu/ass-to-lrc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nattadasu%2Fass-to-lrc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31638441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lrc","lyric-parser","substation-alpha","subtitle-conversion"],"created_at":"2025-12-14T18:05:34.777Z","updated_at":"2026-04-10T10:32:13.796Z","avatar_url":"https://github.com/nattadasu.png","language":"Python","funding_links":["https://github.com/sponsors/nattadasu","https://ko-fi.com/nattadasu","https://patreon.com/nattadasu","https://paypal.me/nattadasu","https://trakteer.id/nattadasu","https://saweria.co/nattadasu"],"categories":[],"sub_categories":[],"readme":"# 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 (≥0.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\u003e [!WARNING]\n\u003e\n\u003e - Not all LRC players support the compact format. Use the `expand` command to convert back to standard format if needed.\n\u003e - **Compact format doesn't support word timing**. If you use `--compact` with `--enhanced`, word timing will be\n\u003e   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: \u003chttps://taskfile.dev/installation/\u003e\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**: `\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e`\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnattadasu%2Fass-to-lrc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnattadasu%2Fass-to-lrc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnattadasu%2Fass-to-lrc/lists"}