Metadata-Version: 2.4
Name: narrately
Version: 0.1.0
Summary: Convert a web article into a spoken mp3 file from its URL
Keywords: tts,text-to-speech,web-scraping,newspaper,gtts,mp3
Author: Alex Brito de las Cuevas
Author-email: Alex Brito de las Cuevas <alextech9106@gmail.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Dist: gtts>=2.5.4
Requires-Dist: lxml-html-clean>=0.4.5
Requires-Dist: newspaper3k>=0.2.8
Requires-Dist: nltk>=3.10.3
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pydantic-settings>=2.15.0
Requires-Python: >=3.13
Project-URL: Repository, https://github.com/alextech9106/narrately
Description-Content-Type: text/markdown

# narrately

Convert a web article, or any text, into a spoken mp3 file.

## Installation

```bash
pip install narrately
```

## Usage

### From a web article URL

```python
from narrately import article_to_audio

output_path = article_to_audio(
    "https://example.com/some-article",
    "article",
    lang="en",
)
print(f"Saved audio to {output_path}")
```

`article_to_audio(url, audio_file_name, lang="en")` downloads and extracts
the article text from `url` (using `newspaper3k`), converts it to speech
(using `gtts`), and saves it as `{audio_file_name}.mp3`. It returns the
`Path` to the generated file.

### From plain text

```python
from narrately import text_to_audio

output_path = text_to_audio(
    "Hello, this text will become an mp3 file.",
    "greeting",
    lang="en",
)
print(f"Saved audio to {output_path}")
```

`text_to_audio(text, audio_file_name, lang="en")` skips the scraping step
and converts `text` directly to speech, saving it as `{audio_file_name}.mp3`.
It returns the `Path` to the generated file.

### Shared arguments

`audio_file_name` can be a plain name (saved in the current directory) or a
full path, e.g. `"output/my_article"` — either way, don't include the `.mp3`
extension, it's appended automatically.

`lang` is a two-letter language code (e.g. `"en"`, `"es"`, `"fr"`) passed
through to `gtts`.

## Notes

- Requires an internet connection: both article scraping and speech
  generation call external services.
- Some sites block automated scraping or require a paid subscription
  (paywalls); in those cases article extraction may fail or return partial
  content.

## License

MIT
