{"id":50760649,"url":"https://github.com/exaroth/narrative","last_synced_at":"2026-06-11T09:31:51.885Z","repository":{"id":361836295,"uuid":"1188696979","full_name":"exaroth/narrative","owner":"exaroth","description":"Listen to ebooks, websites and other text sources in your terminal.","archived":false,"fork":false,"pushed_at":"2026-06-01T12:20:39.000Z","size":10020,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T14:14:31.142Z","etag":null,"topics":["ebook","golang","kittentts","tts"],"latest_commit_sha":null,"homepage":"https://github.com/exaroth/narrative","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exaroth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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}},"created_at":"2026-03-22T13:10:46.000Z","updated_at":"2026-06-01T12:21:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/exaroth/narrative","commit_stats":null,"previous_names":["exaroth/narrative"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/exaroth/narrative","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exaroth%2Fnarrative","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exaroth%2Fnarrative/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exaroth%2Fnarrative/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exaroth%2Fnarrative/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exaroth","download_url":"https://codeload.github.com/exaroth/narrative/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exaroth%2Fnarrative/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34192870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ebook","golang","kittentts","tts"],"created_at":"2026-06-11T09:31:51.322Z","updated_at":"2026-06-11T09:31:51.879Z","avatar_url":"https://github.com/exaroth.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch2 align=\"center\"\u003e\n\u003cimg align=\"center\" width=\"70\" height=\"70\" src=\"https://github.com/exaroth/narrative/releases/download/0.2.0/logosmall.png\" alt=\"\"\u003e\u003cbr/\u003e\n\u003cbr/\u003e\n\nNarrative\n\u003c/h2\u003e\n\nhttps://github.com/user-attachments/assets/9f333e2d-d1eb-4d58-aa6e-77178ccbe425\n\nNarrative streams and converts English language e-books and other text sources for your listening pleasure.\n\n- Uses lightweight [KittenTTS](https://github.com/KittenML/KittenTTS) models for Text-to-Speech conversion, no need for GPU or AI account to run.\n- Supports multiple input formats including __EPUB__, __MOBI__, __AZW3__ , __HTML__, __Markdown__ and plain text.\n- Chapter Selection, Bookmarking support and Playback controls included.\n- Built-in Text to MP3 converter.\n- Voice selection.\n- Built in phoneme editor/debugger.\n- Proudly crafted without use of AI.\n\n## Installation\n\n* Go\n\n```\ngo install github.com/exaroth/narrative/cmd/narrative@latest\n```\n\n* AUR\n\n```\nyay -S narrative\n```\n\n* Homebrew (MacOS)\n\n```\nbrew tap exaroth/narrative\nbrew install narrative\n```\n\n## Usage\n\n```\nUsage: narrative [OPTIONS...] TEXT_SOURCE\nOPTIONS:\n\t-c --convert \u003csource_path\u003e  Convert text source to mp3 file.\n\t-v --voice \u003cvoice_name\u003e     Set voice for playback.\n\t--list-voices               List available voices.\n\t-m --select-model \u003cname\u003e    Run Narrative using given model.\n\t--add-model \u003cname\u003e          Download and select KittenTTS model.\n\t--list-models               List available KittenTTS model information.\n\t-l --select-lib \u003clib\u003e       Run narrative with provided library.\n\t--add-lib \u003clib\u003e             Download and select ONNX lib with given name.\n\t--list-libs                 List available ONNX library for OS/Arch.\n\t-s --speed                  Select playback speed.\n\t--ext-dict                  Path to optional dictionary to override default phonemes.\n\t--init                      Reinitialize Narrative configuration and models.\n\t--help                      Print help.\n```\n\n\nExecuting `narrative` for the first time will prompt for model selection, program will autoconfigure itself afterwards.\n\nTo add new text source simply pass path or url pointing to it as first argument.\n\n### Switching models/libraries\n\nBy default Narrative will use CPU based ONNX library, if you want to use your PC's GPU for inference you can switch library by adding it via `--add-lib` argument, to view available libraries use `--list-libs` command. Library selection is currently only supported on `linux/amd64` architectures.\n\nUse `--add-model` to add/switch TTS model in use.\n\n## Packages\n\nNarrative incorporates set of packages that can be used independently from the main application:\n\n- **Kitten** - [https://github.com/exaroth/narrative/tree/main/pkg/kitten](https://github.com/exaroth/narrative/tree/main/pkg/kitten) - Used for direct interaction with KittenTTS models such as tokenization and inference.\n- **Preprocessor** - [https://github.com/exaroth/narrative/tree/main/pkg/preprocessor](https://github.com/exaroth/narrative/tree/main/pkg/preprocessor) - Prepares input strings for phonemization - eg. does time/currency unit expansion and conversion of numerical values into human readable formats, unicode normalization and a lot more.\n- **Phonemizer** - [https://github.com/exaroth/narrative/tree/main/pkg/phonemizer](https://github.com/exaroth/narrative/tree/main/pkg/phonemizer) - Module for phonemizing inputs, it's based on the [Goruut](https://github.com/neurlang/goruut) library, involving dictionary lookups, phoneme inferrence, punctuation splitting etc.\n- **Reader** - [https://github.com/exaroth/narrative/tree/main/pkg/reader](https://github.com/exaroth/narrative/tree/main/pkg/reader) - Module used for reading and conversion of various text formats for usage within Narrative.\n\n\n## Debugger\n\n\u003cimg width=\"1072\" height=\"725\" alt=\"\" src=\"https://github.com/exaroth/narrative/releases/download/0.2.0/debugger.png\" /\u003e\n\n\u003c/br\u003e\n\nNarrative comes with debugger helpful for editing, modifying and adding phonemes used by Narrative. You can access it with F2 key from within main application or build standalone instance by executing `make build-debugger`. Running debugger will create new dir `narrative-debugger` in the current working directory, inside it  will create 2 files:\n\n- `aux_dict.csv` - Contains phoneme overrides, these will be used instead of phonemes found in default dictionary or inferred by Narrative. Phonemes edited/added by debugger will be automatically added here.\n- `missing_dict.csv` - Contains words that were missing in the built-in dictionary and were inferred by the Narrative.\n\nIn order to add edited phonemes to default dictionary you can use `merge-dicts` utility (eg. by running `just merge-dicts` assuming you are running debugger from within Narrative repo).\n\n## Acknowledgments\n\nNarrative would not be possible without these projects:\n\n- **KitenTTS** [https://github.com/KittenML/KittenTTS](https://github.com/KittenML/KittenTTS)\n- **Goruut** [https://github.com/neurlang/goruut](https://github.com/neurlang/goruut)\n- **KindleUnpack** [https://github.com/kevinhendricks/KindleUnpack](https://github.com/kevinhendricks/KindleUnpack)\n- **Bubbletea** [https://github.com/charmbracelet/bubbletea](https://github.com/charmbracelet/bubbletea)\n- **Beep** [https://github.com/faiface/beep](https://github.com/faiface/beep)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexaroth%2Fnarrative","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexaroth%2Fnarrative","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexaroth%2Fnarrative/lists"}