Notmuch is a separately installed mail index and Emacs interface. Emacsvox adds speech and semantic presentation to its Hello, Search, and Show views; it does not configure a mail store, build the Notmuch database, fetch or send mail, or replace Notmuch’s commands. Install compatible Notmuch command-line and Emacs components and complete their setup first. The official Notmuch Emacs manual covers that setup and the complete upstream command set.
The generated emacsvox-notmuch in Emacsvox Reference Manual section is the exhaustive Emacsvox command and option reference. This chapter follows the tasks a user performs and explains when automatic feedback occurs.
Run M-x notmuch to open Notmuch Hello. With the standard Emacsvox global
maps loaded, C-' m runs notmuch-search directly and prompts for a
query. Emacsvox loads its live integration when Notmuch loads and marks new
Hello, Search, Show, and Tree buffers with Notmuch semantic context.
Notmuch remains the authority for every database, tag, archive, attachment, and message-composition operation. Emacsvox observes the result of an explicit upstream command and presents it; loading the integration by itself does not alter mail, tags, files, or Notmuch configuration.
Moving among Hello widgets speaks a saved-search label and its displayed message count, or identifies the button or link reached. These are the common Hello keys in the current Notmuch map:
Run widget-forward to reach the next saved search, entry field, button,
or link.
Run widget-backward to reach the preceding widget.
Run widget-button-press; on a saved search this starts its query.
Run notmuch-jump-search and choose a configured search.
Run notmuch-refresh-this-buffer to refresh Hello.
Run notmuch-mua-new-mail. Composition then belongs to Message mode and
the separate emacsvox-message integration.
Press ? in any Notmuch view, or C-h m, for the complete bindings provided by the installed Notmuch version.
A Notmuch search buffer can appear before its rows have finished rendering. For a user-owned non-refresh search that remains selected, Emacsvox gives a progress cue and waits for Notmuch’s process sentinel. It does not announce an empty row or move point while the process is still producing results.
The default adaptive completion policy distinguishes two interactions:
The notification stream uses tts-notification-device when one is
available and otherwise falls back to the primary process. The
summary policy always sends a generic count there; cue sends only
a completion cue; and silent suppresses successful completion.
Failures remain audible and generic for every policy. A normal refresh is
always treated as background-style completion, while the deliberate global
refresh-all command remains silent.
Opening a thread speaks one semantic message summary and the first visible body line. Hidden alternative bodies are skipped. If a message has no visible body text, point falls back to a leaf MIME-part button when possible. Moving onto such a button identifies its bounded filename, content type, and size.
Run notmuch-show-next-open-message.
Run notmuch-show-previous-open-message.
Run notmuch-show-next-message, including closed messages.
Run notmuch-show-previous-message, including closed messages.
Run notmuch-show-advance-and-archive. Within one message Emacsvox reads
the newly visible page; on a message transition it reads the new message; at
the thread end it reports the actual archive outcome and destination.
Run notmuch-show-rewind and read the resulting page or message.
Run notmuch-show-toggle-message and cue the current message’s resulting
visibility.
Run notmuch-show-open-or-close-all. It opens every message and reports
the resulting thread state and total, such as “Opened all 5 messages.” Use a
prefix argument, C-u M-RET, to close every message and receive the
corresponding total.
Run emacsvox-notmuch-speak-show-position. It reports the message
ordinal and total plus complete configured message details. On a MIME-part
button it instead gives the complete part description, including its full
filename.
Run notmuch-show-next-button and identify the button or MIME part.
Run notmuch-show-previous-button and identify the button or MIME part.
Run notmuch-show-save-attachments. Emacsvox confirms when the upstream
command returns, but Notmuch does not expose a per-attachment result through
this command, so the confirmation cannot distinguish partial skips.
Run notmuch-show-save-part on the current MIME part.
Run notmuch-show-view-part.
Run notmuch-show-interactively-view-part and choose an external action.
Run notmuch-show-choose-mime-of-part.
Viewing, saving, overwriting, or launching a MIME part remains an explicit Notmuch operation. Merely navigating or requesting details never opens an attachment or external viewer.
Emacsvox compares displayed tags before and after interactive mutation. It reports only the actual additions and removals. Adding an existing tag or removing an absent one reports “Tags unchanged” rather than claiming a change. An error or cancelled upstream command does not produce success feedback.
The following common Show commands receive that result-aware feedback:
Run notmuch-show-add-tag on the current message.
Run notmuch-show-remove-tag.
Run notmuch-show-tag-all across the thread.
Run notmuch-show-archive-message-then-next-or-next-thread.
Run notmuch-show-archive-thread-then-next.
Archive feedback distinguishes a real change, unchanged archive tags, and an
unset notmuch-archive-tags configuration. Movement wrappers give one
combined result rather than duplicating feedback from their nested tag or
archive command.
Run M-x customize-group RET emacsvox-notmuch RET to change Notmuch speech without altering Notmuch’s own database or display.
emacsvox-notmuch-search-result-fieldsDefaults to (authors subject date count tags). Remove subject or
another field to keep it out of Search navigation speech, reorder fields, or
add a formatter function.
emacsvox-notmuch-show-message-fieldsDefaults to (from date to cc tags attachments). The subject is omitted
by default in Show, while To and Cc recipients are included. Remove
to, cc, or any other field when recipient privacy matters.
emacsvox-notmuch-search-field-separatoremacsvox-notmuch-show-field-separatorControl the text placed between configured fields; both default to comma and space.
emacsvox-notmuch-search-status-iconsemacsvox-notmuch-show-status-iconsMap unread, replied, forwarded, flagged, and personal status tags to cues or
silence. Removing an entry makes that status available to ordinary tag
speech. The optional Aural Presentation feature
mail-message-status-cues can own shared semantic mail-state cues.
emacsvox-notmuch-search-completion-styleChoose adaptive, summary, cue, or silent as
described under asynchronous completion.
Mail-controlled text is bounded before automatic speech and Aural history. The defaults are 256 characters and 1,024 UTF-8 bytes per field, then 1,000 characters and 4,096 bytes for the complete automatic presentation:
emacsvox-notmuch-automatic-field-character-limitemacsvox-notmuch-automatic-field-byte-limitBound each automatic field before formatting and submission.
emacsvox-notmuch-automatic-total-character-limitemacsvox-notmuch-automatic-total-byte-limitProvide the final defense for one automatic Notmuch presentation.
emacsvox-notmuch-mime-node-limitemacsvox-notmuch-mime-depth-limitDefault to 4,096 cons nodes and depth 64. They keep malformed, cyclic, broad, or deeply nested MIME metadata from exhausting automatic inspection. An incomplete scan reports a conservative attachment lower bound instead of claiming that no attachment exists.
A shortened Search or Show presentation states what was omitted and points to C-c C-p for explicit full configured details; a shortened Hello item points to RET. The explicit Search and Show inspection commands deliberately bypass the automatic content limits; use them only when speaking the complete configured fields is appropriate.
Primary-stream Notmuch presentations can enter bounded Aural Presentation
history. By default Emacsvox retains at most 20 presentations and at most
4,096 UTF-8 bytes of speech preview per record; records contain frozen data,
source names, and positions, but never retain source buffers. Run
M-x emacsvox-aural-list-recent-feedback to inspect what was retained, or
set emacsvox-aural-presentation-history-limit to zero to disable that
history.
Generic asynchronous completion uses the notification stream and contains no
query or message metadata, but notification text may be retained by the
notification subsystem. Choose cue or silent when even a generic
thread count is unwanted, and review the global notification-device and log
settings separately.
Widget navigation, view lifecycle, and searches have Notmuch-specific semantic feedback.
Result navigation, asynchronous lifecycle, tags, archive operations, opening, and configured detail inspection have Notmuch-specific feedback.
Message and part navigation, page reading, visibility, tags, archive operations, and explicit detail inspection have Notmuch-specific feedback.
Tree buffers receive emacsvox-aural-module context only. Generic core
speech can still operate, but this module currently has no Tree-specific row
formatter, navigation, mutation, visibility, or asynchronous lifecycle.
Notmuch uses standard Message-mode composition. Speech support after
notmuch-mua-new-mail, reply, forward, or resume transitions belongs to
emacsvox-message, not to the Notmuch integration.
There is no independent Notmuch speech disable or unload command. Advice, hooks, and the Search arrow bindings remain installed for the Emacs session once the module loads. Repeated loading is idempotent and does not duplicate them.
Use ? or C-h m in the affected Notmuch buffer to confirm the keys provided by the installed Notmuch version. Run M-x notmuch-version to identify that package, and use the official manual linked at the beginning of this chapter for its current behavior.
Run M-x emacsvox-aural-doctor when speech bindings, loaded source versus byte-code, Aural rules, sound resources, or the backend appear wrong. Use M-x emacsvox-aural-list-recent-feedback to inspect the exact bounded presentation submitted for a Notmuch action. These diagnostics do not query or modify the mail database.
If you are changing the integration rather than using it, see Integration Maintenance for the build, test, renderer, and asynchronous lifecycle contracts.