diff --git a/docs/source/index.rst b/docs/source/index.rst index 6e12948..0828092 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,8 +12,10 @@ Main Features ------------- - Convert ASS/SSA subtitles to SRT format +- **Style filtering**: Export only specific subtitle styles - Remove effects from subtitle text (optional) - Remove and merge consecutive duplicate dialogues (optional) +- List available styles in ASS files - Support for both string paths and Path-like objects - Command-line interface (CLI) for easy usage @@ -71,6 +73,19 @@ Here's a basic example of how to use pyasstosrt: sub = Subtitle('subtitle.ass') sub.export(output_dir='output', encoding='utf-8') + # Export only default dialogue styles + sub = Subtitle('subtitle.ass', only_default_style=True) + sub.export() + + # Export specific styles + sub = Subtitle('subtitle.ass', include_styles=['Default', 'Alt']) + sub.export() + + # List available styles + sub = Subtitle('subtitle.ass') + styles = sub.get_styles() + print(styles) # ['Default', 'Signs', 'Credits', ...] + Command Line Interface -------------------- @@ -99,6 +114,18 @@ The library provides a command-line interface for easy usage: # Print dialogues to console pyasstosrt export subtitle.ass --output-dialogues + # List available styles + pyasstosrt styles subtitle.ass + + # Export only default dialogue styles + pyasstosrt export subtitle.ass --only-default + + # Export specific styles + pyasstosrt export subtitle.ass --include-styles "Default,Alt" + + # Exclude specific styles + pyasstosrt export subtitle.ass --exclude-styles "Signs,Credits" + # Run without installation using uvx uvx --from 'pyasstosrt[cli]' pyasstosrt export * --remove-effects --remove-duplicates diff --git a/docs/source/pyasstosrt/cli.rst b/docs/source/pyasstosrt/cli.rst index 91be343..2602779 100644 --- a/docs/source/pyasstosrt/cli.rst +++ b/docs/source/pyasstosrt/cli.rst @@ -18,10 +18,19 @@ The basic command syntax is: Where `FILEPATH...` is one or more paths to ASS subtitle files. -Options -------- +Commands +-------- + +``export`` + Convert ASS/SSA subtitle file(s) to SRT format. + +``styles`` + List all unique styles found in an ASS subtitle file. + +Export Options +-------------- -The CLI supports the following options: +The ``export`` command supports the following options: ``--remove-effects, -r`` Remove effects from subtitles. @@ -29,6 +38,15 @@ The CLI supports the following options: ``--remove-duplicates, -d`` Remove duplicate subtitles. +``--only-default, -D`` + Export only styles containing 'Default' in name (excludes Signs, Credits, etc.). + +``--include-styles, -i TEXT`` + Comma-separated list of style names to include (e.g., 'Default,Signs'). + +``--exclude-styles, -x TEXT`` + Comma-separated list of style names to exclude (e.g., 'Signs,Credits_dvd'). + ``--output-dir, -o PATH`` Output directory for the SRT file(s). @@ -41,6 +59,18 @@ The CLI supports the following options: ``--version, -v`` Show version and exit. +.. note:: + The style filtering options (``--only-default``, ``--include-styles``, ``--exclude-styles``) + are mutually exclusive. You can only use one at a time. + +Styles Command Options +---------------------- + +The ``styles`` command supports the following options: + +``--table, -t`` + Display styles in a formatted table. + Examples -------- @@ -126,3 +156,73 @@ You can combine multiple options: .. code-block:: bash pyasstosrt export subtitle.ass --remove-effects --remove-duplicates --output-dir ./output + +Style Filtering +-------------- + +List Available Styles +~~~~~~~~~~~~~~~~~~~~ + +Before filtering styles, you can list all available styles in a subtitle file: + +.. code-block:: bash + + pyasstosrt styles subtitle.ass + +Display styles in a formatted table: + +.. code-block:: bash + + pyasstosrt styles subtitle.ass --table + +Export Only Default Styles +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Export only dialogue styles (excludes signs, credits, etc.): + +.. code-block:: bash + + pyasstosrt export subtitle.ass --only-default + +Include Specific Styles +~~~~~~~~~~~~~~~~~~~~~~ + +Export only specific styles by name: + +.. code-block:: bash + + pyasstosrt export subtitle.ass --include-styles "Default,Alt" + +Include multiple styles: + +.. code-block:: bash + + pyasstosrt export subtitle.ass --include-styles "Default,Thoughts,Narration" + +Exclude Specific Styles +~~~~~~~~~~~~~~~~~~~~~~ + +Export all styles except specific ones: + +.. code-block:: bash + + pyasstosrt export subtitle.ass --exclude-styles "Signs,Credits" + +Exclude multiple styles: + +.. code-block:: bash + + pyasstosrt export subtitle.ass --exclude-styles "Signs,Credits_dvd,Opening,Ending" + +Combine Style Filtering with Other Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can combine style filtering with other conversion options: + +.. code-block:: bash + + pyasstosrt export subtitle.ass --only-default --remove-effects --remove-duplicates + +.. code-block:: bash + + pyasstosrt export subtitle.ass --include-styles "Default,Alt" --output-dir ./output diff --git a/docs/source/pyasstosrt/subtitle.rst b/docs/source/pyasstosrt/subtitle.rst index 3fdfd0a..033dca6 100644 --- a/docs/source/pyasstosrt/subtitle.rst +++ b/docs/source/pyasstosrt/subtitle.rst @@ -18,6 +18,7 @@ Subtitle ~Subtitle.convert ~Subtitle.export ~Subtitle.get_text + ~Subtitle.get_styles ~Subtitle.remove_duplicates ~Subtitle.subtitle_formatting ~Subtitle.text_clearing @@ -35,6 +36,9 @@ Subtitle ~Subtitle.dialogues ~Subtitle.removing_effects ~Subtitle.is_remove_duplicates + ~Subtitle.only_default_style + ~Subtitle.include_styles + ~Subtitle.exclude_styles .. rubric:: Examples @@ -98,3 +102,88 @@ Advanced Usage ) sub.convert() sub.export('output/directory', encoding='utf-8') + +Style Filtering +-------------- + +List Available Styles +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from pyasstosrt import Subtitle + + # Get list of available styles + sub = Subtitle('subtitle.ass') + styles = sub.get_styles() + print(f"Available styles: {styles}") + +Export Only Default Styles +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from pyasstosrt import Subtitle + + # Export only dialogue styles (excludes signs, credits, etc.) + sub = Subtitle('subtitle.ass', only_default_style=True) + sub.export() + +Include Specific Styles +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from pyasstosrt import Subtitle + + # Export only specific styles + sub = Subtitle('subtitle.ass', include_styles=['Default', 'Alt']) + sub.export() + + # Or as a single style + sub = Subtitle('subtitle.ass', include_styles=['Default']) + sub.export() + +Exclude Specific Styles +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from pyasstosrt import Subtitle + + # Export all styles except specific ones + sub = Subtitle('subtitle.ass', exclude_styles=['Signs', 'Credits']) + sub.export() + + # Exclude multiple styles + sub = Subtitle('subtitle.ass', exclude_styles=['Signs', 'Credits_dvd', 'Opening', 'Ending']) + sub.export() + +Combine Style Filtering with Other Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from pyasstosrt import Subtitle + + # Combine style filtering with effects removal + sub = Subtitle( + 'subtitle.ass', + only_default_style=True, + removing_effects=True, + remove_duplicates=True + ) + sub.export('output') + + # Include specific styles with custom options + sub = Subtitle( + 'subtitle.ass', + include_styles=['Default', 'Thoughts'], + removing_effects=True + ) + sub.export('output', encoding='utf-8') + +.. note:: + The style filtering options (``only_default_style``, ``include_styles``, ``exclude_styles``) + are mutually exclusive. You can only use one at a time. If you try to use multiple, + a ``ValueError`` will be raised.