Noctua for Obsidian

Send any note (or selection) to Noctua and listen to it later as an episode in your personal podcast feed. Noctua turns your text into natural-sounding audio with text-to-speech (TTS), so you can listen to your notes on the go, and you can save episode transcripts back into your vault.

What it does

• Send note to your podcast feed — command, ribbon icon, or right-click a note in the file explorer

• Send selection to your podcast feed — convert just the highlighted text

• Shows progress while Noctua prepares the audio, and confirms when the episode is in your feed

• Optionally writes noctua_id and noctua_url into the note's frontmatter so the same note isn't sent twice by accident

• Save episode transcripts to your vault — optionally save the transcript automatically once an episode is ready, or on demand:

  • Save transcript of this note's episode — for a note you've already sent (uses its noctua_id)
  • Save episode transcripts from your podcast feed — browse the episodes in your Noctua account and save the transcripts of the ones you choose (see Saving transcripts from your feed)

  Transcripts are saved as notes in the Transcript folder (default Noctua transcripts) with noctua_transcript_of, noctua_url, source and created properties. Saving the same episode again refreshes the existing note rather than creating a duplicate. When sent-note marking is on, the sent note gets a noctua_transcript link to its transcript.

• Works on desktop and mobile (requires Obsidian 1.13.0+)

Installation

The plugin is published in the Obsidian community plugin directory: Noctua on community.obsidian.md.

To install it from inside Obsidian:

1. Open Settings → Community plugins. If you see Restricted mode is on, click Turn on community plugins.
2. Click Browse, search for Noctua and click Install.
3. Click Enable, then follow Setup below.

To run a build from this repository instead, see Installing a local build in Obsidian.

Setup

1. Sign in at cast.noctua.uno and open Settings → API keys
2. Create a key (e.g. labelled "Obsidian") and copy it — it is shown only once
3. In Obsidian, open Settings → Noctua and paste the key
4. Use Test connection to confirm it works and see your remaining credits

Saving transcripts from your feed

You can save the transcript of any episode in your Noctua account, not just notes you sent from Obsidian. This includes episodes made from web articles, emails or the Noctua web app.

1. Open the command palette (Ctrl/Cmd + P) and run Noctua: Save episode transcripts from your podcast feed.

2. A window lists your episodes, newest first. Each one shows its date, and also:

   • its status (for example processing or expired) if it isn't completed
   • transcript saved if its transcript is already in your vault

   Failed episodes aren't listed because they have no transcript.

3. Type in the Filter episodes by title box to narrow the list. Each word you type must appear in the title, in any order.

4. Tick the episodes you want. Ticks are kept when you change the filter, so you can search for one episode, tick it, clear the search and look for another. To select several at once:

   • Select shown ticks every episode in the current (filtered) list
   • Select unsaved ticks only the shown episodes whose transcript isn't in your vault yet
   • Clear unticks everything

   The line above the list shows how many episodes are selected and how many are shown.

5. Click Save N transcripts. The button stays disabled until at least one episode is ticked.

The transcripts are saved one at a time, with a progress message such as Saving transcript 2 of 5: "Weekly review"…. When they're done:

• A summary shows how many were saved and in which folder, and lists any that failed with the reason.
• If you saved a single transcript, its note opens.
• Each transcript is saved to your Transcript folder (set it in Settings → Noctua; default Noctua transcripts). If the episode already has a transcript note, that note is updated wherever you've moved it, and any properties you added are kept.

A few things to know:

• Episodes that are still processing can fail with no transcript for this episode yet. Noctua has the transcript once it has extracted the content. Run the command again a little later.
• Expired episodes can still be saved: the transcript stays available after the audio expires.
• Only your 100 most recent episodes are listed. If you have more, the window says Showing your 100 most recent episodes of N.
• If Noctua rejects your API key, saving stops straight away and the remaining episodes are marked skipped. Check the key in Settings → Noctua and use Test connection.

Network use & privacy disclosure

This plugin sends data to the Noctua API (api.cast.noctua.uno) — this is its entire purpose and it only happens when you explicitly trigger a send:

• What is sent: the content of the note (or selection) you choose to send, its title, and an obsidian:// link containing your vault name and the note's path (stored with the episode to identify its source; it is not included in your podcast RSS feed or on public share pages)
• When: only when you run a send command; nothing is sent in the background
• What is downloaded: episode transcripts, and your episode list when you open the episode picker — only when you run a transcript command or have Save transcripts turned on
• Telemetry: none — the plugin collects no analytics or usage data

Vault access

The plugin reads and writes files in your vault only through Obsidian's API, and only for these tasks:

• Reading the note you send (or the selected text).
• Writing noctua_id, noctua_url and noctua_transcript to the frontmatter of a sent note (if sent-note marking is on), and creating or updating transcript notes in your Transcript folder.
• Listing the Markdown files in your vault when it saves a transcript or opens the episode picker. It checks each file's frontmatter for a noctua_transcript_of property to find transcripts you've already saved. That's how saving the same episode twice updates your existing note (even if you've moved it out of the transcript folder), and how the picker marks episodes as transcript saved. It reads the frontmatter from Obsidian's metadata cache, not the note contents.

None of this vault information is sent to Noctua or anywhere else. The only data sent is what's listed above.

A Noctua account is required, and each conversion consumes one Noctua credit (new accounts include free credits; more can be purchased). See Noctua's privacy policy and terms.

Your API key is stored in Obsidian's secret storage, so it is never written to the plugin's data.json inside your vault and is not picked up by vault syncs or backups. Secret storage needs Obsidian 1.11.4+, and the plugin's settings use the declarative settings API added in 1.13.0, so 1.13.0 is the minimum supported version. A key saved by an earlier plugin version is migrated into secret storage and removed from data.json on first run.

Development

npm install
npm run dev      # esbuild watch mode
npm test         # vitest unit tests
npm run build    # type-check + production bundle (main.js)

Installing a local build in Obsidian

Obsidian loads community plugins from <vault>/.obsidian/plugins/<plugin id>/. For this plugin the folder must be named noctua, to match the id in manifest.json. The folder needs three files: main.js, manifest.json and styles.css.

It's best to test in a separate vault rather than your everyday one. If the published version is already installed in that vault, the local build replaces it, because both use the same folder.

1. Build the plugin

npm install
npm run build    # writes main.js to the repository root

2. Put the plugin in your vault using one of these options.

• Option A: link the repository (best while developing). Obsidian then loads the files straight from your checkout, so every rebuild is picked up:

  mkdir -p "<vault>/.obsidian/plugins"
  ln -s "$(pwd)" "<vault>/.obsidian/plugins/noctua"
  

  Obsidian writes the plugin's settings to data.json in this folder. That file is in .gitignore, so it won't be committed.

• Option B: copy the files.

  mkdir -p "<vault>/.obsidian/plugins/noctua"
  cp main.js manifest.json styles.css "<vault>/.obsidian/plugins/noctua/"
  

  Copy the files again after each build.

.obsidian is a hidden folder. On macOS, press Cmd + Shift + . in Finder to show hidden files.

3. Enable the plugin in Obsidian

1. Open Settings → Community plugins.
2. If you see Restricted mode is on, click Turn on community plugins.
3. Under Installed plugins, find Noctua and switch it on. If it isn't listed, click the refresh icon next to Installed plugins.
4. Follow Setup to add your API key. The key is kept in Obsidian's secret storage on this device, not in the plugin folder.

4. Load your changes

• Run npm run dev to rebuild main.js automatically whenever you save a source file.
• Obsidian doesn't reload a plugin by itself. After a rebuild, switch Noctua off and on again in Settings → Community plugins, or run Reload app without saving from the command palette.
• If you used Option B, copy the files into the vault again first.
• Open the developer console (Cmd + Option + I on macOS, Ctrl + Shift + I on Windows/Linux) to see errors from the plugin.

Releasing

npm version <patch|minor|major> bumps package.json, manifest.json and versions.json together. Push the tag (no v prefix, so it matches manifest.json) and the release workflow builds and drafts a GitHub release with main.js, manifest.json and styles.css attached:

npm version patch
git push && git push --tags

License

MIT