Note Narrator

Note Narrator

Note Narrator is an Obsidian plugin that reads your notes aloud using text to speech. It uses ElevenLabs voices, starts playing while the rest of the note is still being generated, and can save the audio as an .mp3 next to your note.

Requires an ElevenLabs account and API key, and ElevenLabs charges for the audio it generates (credits on your plan; free tier limits apply). The text you read is sent to ElevenLabs. See Requirements and costs and Disclosures before installing.

What it does

• Reads the whole note, or just your text selection, from a sidebar panel or the Read note aloud command (Stop reading stops it).
• Narrator profiles: a provider, a voice and its settings, and optional per-profile reading options. Switch profiles from the panel.
• Plays as soon as the first chunk is ready, and generates long notes in the background while you listen.
• Optionally saves the audio to your vault, links it from the note, and tells you when it is outdated.
• Optionally highlights the text being read and scrolls the note to it.
• Works on desktop and mobile.

Documentation

Full documentation is at the Note Narrator docs:

• Installation and Quick start
• Settings: every setting, tab by tab
• Supported platforms and Privacy and network use
• Troubleshooting and FAQ and the Roadmap

Install

Note Narrator is not in the Obsidian community plugin directory yet. Requires Obsidian 1.13.1 or newer.

• BRAT (recommended): install BRAT, run BRAT: Add a beta plugin for testing, and enter pablokvitca/note-narrator.
• Manually: download main.js, manifest.json and styles.css from the latest release into <your vault>/.obsidian/plugins/note-narrator/, then enable it under Settings → Community plugins.

Quick start

1. Create an ElevenLabs account and API key. Then open Settings → Note Narrator → Providers, open the ElevenLabs provider and choose your API key.
2. Open a note, click the audio-lines icon in the ribbon (or the note's toolbar) to open the panel, and press Read.

Requirements and costs

• You need an ElevenLabs account and API key. Note Narrator is free, but ElevenLabs charges for the audio it generates (credits on your ElevenLabs plan, and free tier limits apply). You are responsible for those costs.
• Reading needs an internet connection. There is no offline mode yet.
• Saved audio replays for free. Regenerating it, or reading again, uses credits again.
• ElevenLabs' terms apply to you and the audio. You must be 18 or over (or of legal age where you live). Free accounts may use the service for non-commercial purposes only, while paid plans may use it commercially. Check your plan before using saved audio commercially.

Disclosures

Obsidian asks plugins to be clear about what they do with your data. For Note Narrator:

• Network use. The plugin talks to one external service, ElevenLabs (api.elevenlabs.io), and only in these cases:
  • Reading and regenerating audio (including background generation, and "Auto-generate on open" if you turn it on, which also needs saving and linking turned on): sends the text being read, the chosen voice and model settings, and your API key. Requests that ElevenLabs rate-limits are retried automatically and resend the same text, which can use more credits.
  • Listing voices: sends your API key whenever you open a narrator profile's settings (with an API key set) or press the voice refresh button.
  • Naming a saved audio file after its voice: sends your API key and the voice ID, each time audio is saved (including automatic saves).
  • Replaying saved audio needs no network access and uses no credits.
• What is read. The text sent is the note or selection after Markdown is stripped, plus the note title and properties if you enabled those. Anything you read leaves your device and is processed by ElevenLabs under their Terms of Service and Privacy Policy. The plugin author has no control over how ElevenLabs stores or uses that data. Do not read notes containing text you are not willing to send to them.
• Your API key is stored in Obsidian's built-in secret storage, not in the plugin's data.json. Only the name of the secret is saved.
• Files it writes. Settings in the plugin's data.json. If you turn on saving: .mp3 files in your vault (next to the note, or in a folder you choose) and, with linking on, a few properties in the note's frontmatter. Clear Note Narrator files moves the linked .mp3 to the trash (following your vault's deletion setting) and removes those properties. The plugin does not read or write files outside your vault.
• No telemetry, no ads, no self-updates. The plugin collects no usage data, shows no advertising, and does not install or update itself or any code.
• Synthetic voices. The audio is AI-generated. If you share it, consider saying so, and follow ElevenLabs' rules on voice rights and permitted content (see their Prohibited Use Policy).

What to expect

• It is an early version (0.x). Behaviour and settings can change between releases, and existing settings are migrated when they do.
• HTML comments (<!-- like this -->) are not skipped and are read as text. Obsidian comments (%% like this %%) can be skipped.
• Editing a note marks its saved audio as outdated, even if the edit was outside the text that was read.
• Highlighting needs the note open in Editing view and is approximate at chunk and section boundaries.
• More known limitations and the roadmap are in the documentation.

Disclaimer

Note Narrator is provided "as is", without warranty of any kind. The author is not liable for any costs, data loss, or other damages arising from its use, including ElevenLabs charges. It is an independent project, not affiliated with, endorsed by, or sponsored by ElevenLabs or Obsidian. All trademarks belong to their owners.

License

The source code is open: github.com/pablokvitca/note-narrator. The main.js in each release is built from this repository by GitHub Actions. Released under the 0BSD license. Third-party attributions and notices are in THIRD_PARTY_NOTICES.md.

Development

npm i to install, npm run dev to build in watch mode, npm run build to type-check and produce a production main.js, npm run lint and npm test to check. The branching model and release process are in AGENTS.md.