Thursday, July 27, 2017

Data-Binding In Emacs Lisp: let-alist When Processing JSON Data

Data-Binding In Emacs Lisp: let-alist When Processing JSON Data

1 Summary

Module json-read consumes JSON data structures and transforms them
into their elisp equivalent, where JSON dictionaries become alists and
JSON arrays become vectors. Accessing that data from lisp would
ordinarily require using lisp accessors such as assoc, car and
cdr. With let-alist, we get data-binding for free — the result
is elisp code that uses dotted-variables to directly access specific
slots in a deeply nested data structure. Thus, processing data
available as JSON via Web APIs is a really good use-case for
let-alist. Long-standing wish — I wish Emacs' JSON parsing were
implemented in native code rather than in elisp.

1.1 A Working Example

I recently implemented myself a NOAA Weather API Client — it pulls
the NOAA Weather Forecast (weekly and hourly) as JSON objects, and
produces an org-mode buffer that renders the data.
Note that though the above is part of a much larger
emacspeak-wizards module, the above function and its dependencies
are themselves mostly independent of Emacspeak, except for the last
two forms in the weather forecast function.
Here is an annotated version of the function that gets NOAA data and
leverages let-alist to process the results:

(defun ems--noaa-get-data (ask)
  "Internal function that gets NOAA data and returns a results buffer."
  (declare (special gweb-my-address))
  (let* ((buffer (get-buffer-create "*NOAA Weather*"))
         (inhibit-read-only  t)
         (date nil)
         (start (point-min))
         (address (when ask (read-from-minibuffer "Address:")))
         (geo  (when ask (gmaps-geocode address))))
    (unless address (setq address gweb-my-address))
    (with-current-buffer buffer
      (setq header-line-format (format "NOAA Weather For %s" address))
      (insert (format "* Weather Forecast For %s\n\n" address))
;;; produce Daily forecast
      (let-alist (g-json-from-url (ems--noaa-url geo))
         for p across .properties.periods do
         (let-alist p
             "** Forecast For %s: %s\n\n%s\n\n"
             .name .shortForecast .detailedForecast)))
         (fill-region start (point)))
         (format "\nUpdated at %s\n"
                 (ems--noaa-time "%c" .properties.updated))))
      (let-alist ;;; Now produce hourly forecast
          (g-json-from-url (concat (ems--noaa-url geo) "/hourly"))
         (format "\n* Hourly Forecast:Updated At %s \n"
                 (ems--noaa-time "%c" .properties.updated)))
         for p across .properties.periods do
         (let-alist p
           (unless (and date (string= date (ems--noaa-time "%x" .startTime)))
             (insert (format "** %s\n" (ems--noaa-time "%A %X" .startTime)))
             (setq date (ems--noaa-time "%x" .startTime)))
             "  - %s %s %s:  Wind Speed: %s Wind Direction: %s\n"
             (ems--noaa-time "%R" .startTime)
             .temperature .windSpeed .windDirection)))))
      (goto-char (point-min)))

  1. In the above_ /gweb-my-address_ is a Lat/Lng pair as returned by
    gmaps-geocode defined in g-client/gmaps.el. That is used as the
    default location for which we retrieve the forecast.
  2. Parameter ask if non-nil results in the user being prompted
    for the address — that address is then geocoded using
    the Google Maps API.
  3. The weather forecast display will leverage org-mode for
    structured navigation; however we dont want that buffer to be
    editable in general; moreover special-mode gives us nice
    features such as q for quitting that window. So we use
    special-mode as the major mode, and orgstruct-mode as a minor
    mode to get the best of both worlds.
  4. The API call to NOAA results in a JSON data structure where holds an array of forecast
    objects. Using that result in let-alist gives us data binding
    for free! Notice the following:
    1. We can use .properties.periods in the cl-loop as the list
      to iterate over.
    2. Within that loop body, a second let-list enables data
      binding over the forecast object that we are processing in the
      loop body.
    3. Data accesses inside the loop body are again simple given the
      data binding created by the let-alist.

The code for generating the hourly forecast is similar in spirit —
the main take-away here is that let-alist saves a lot of
boiler-plate code that would have been otherwise required to take
apart the nested list structure we got back with our data.

Monday, July 24, 2017

Spatial Audio: ALSA Virtual Devices Using LADSPA

Spatial Audio: ALSA Virtual Devices Using LADSPA

1 Overview

I have long wanted to apply HRTF filters to soundscapes on the
Emacspeak Audio Desktop to produce effects that are better
spatialized. I just got this working over the weekend using LADSPA
Plugin from package zam-plugins.

2 Getting ZAM Plugins

git clone 

And follow the instructions in the README file.

Next, do

sudo make install

to install the plugins.

Finally, make sure that the install location is on your LADSPA path.

2.1 Adding HRTF Virtual Devices Via ASOUNDRC

After updating Emacspeak from GitHub,
open file servers/linux-outloud/asoundrc
and copy the section marked HRTF to your personal .asoundrc
this defines a number of virtual devices that use the newly installed
LADSPA plugin.
Beware: Back-up your .asoundrc first and make sure you can restore
it even if you lose speech.

3 Spatialized Soundscapes

In a running Emacspeak session, invoke command


with an interactive prefix arg and specify one of the available
devices using standard Emacs completion.

For use with Soundscapes, I recommend one of the devices that place
sound directly in front of the listener (azimuth 0) but with a non-0

The HRTF devices are named with prefix tts because I would like to
use these with software TTS; but for now the result with TTS is not
as good as it is with Soundscapes.

Notice that command soundscape-restart offers a number of virtual
ALSA devices based on your .asoundrc; see the next section for a

4 Virtual ALSA Devices For Use As A Soundscape Filter

Here is a list of available LADSPA devices in my setup that can be
used to add additional effects to Soundscapes:

  • crossfeed: Apply a BS2B filter.
  • default: No filters, vanilla audio.
  • tap-reverb: Reverb filter from package tap-plugins.
  • reverb-crossfeed: Reverb filter followed by BS2B.
  • tts-a0-e15: HRTF at (0, 15).
  • tts-a0-e30: HRTF at (0, 30).
  • tts-a0-e60: HRTF at (0, 60).
  • tts-a0-e90: HRTF at (0, 90).
  • tts-a0-em15: HRTF at (0, -15).
  • tts-a0-em30: HRTF at (0, -30).
  • tts-a0-em45: HRTF at (0, -45).
  • tts-a135-e45: HRTF at (135, 45).
  • tts-a135-em45: HRTF at (135, -45).
  • tts-a225-e45: HRTF at (225, 45).
  • tts-a225-em45: HRTF at (225, -45).
  • tts-a45-e45: HRTF at (45, 45).
  • tts-a45-em45: HRTF at (45, -45).
  • tts-am45-e45: HRTF at (-45, 45).
  • tts-am45-em45: HRTF at (-45, -45).

5 Other Uses Of HRTF Devices

You can experiment with these devices using aplay e.g.:

aplay -Dtts_a0_e0 filename.wav

You can also apply the HRTF Ladspa plugin from within MPlayer when
using emacspeak.
To try this, use C-e ; f and pick the Zam effect when prompted.
Invoke that command with an interactive prefix arg — C-u C-e ; f
— to edit the params passed to the Zam filter.

HRTF filters when playing media are mostly useful to position a
radio station in 3d space when playing more than one station

Sunday, April 30, 2017

Emacspeak 46.0 (HelpfulDog) Unleashed

Emacspeak 46.0—HelpfulDog—Unleashed!

For Immediate Release:

San Jose, Calif., (May 1, 2017)

Emacspeak 46.0 (HelpfulDog): Redefining Accessibility In The Age Of Smart Assistants
–Zero cost of Ownership makes priceless software Universally affordable!

Emacspeak Inc (NASDOG: ESPK) — — announces the
immediate world-wide availability of Emacspeak 46.0 (HelpfulDog) — a
powerful audio desktop for leveraging today's evolving data, social
and service-oriented Internet cloud.

1 Investors Note:

With several prominent tweeters expanding coverage of
#emacspeak, NASDOG: ESPK has now been consistently trading over
the social net at levels close to that once attained by DogCom
high-fliers—and as of May 2017 is trading at levels close to
that achieved by once better known stocks in the tech sector.

2 What Is It?

Emacspeak is a fully functional audio desktop that provides complete
eyes-free access to all major 32 and 64 bit operating environments. By
seamlessly blending live access to all aspects of the Internet such as
Web-surfing, blogging, social computing and electronic messaging into
the audio desktop, Emacspeak enables speech access to local and remote
information with a consistent and well-integrated user interface. A
rich suite of task-oriented tools provides efficient speech-enabled
access to the evolving service-oriented social Internet cloud.

3 Major Enhancements:

This version requires emacs-25.1 or later.

  1. Audio-formatted Mathematics using NodeJS. ⟋🕪
    1. DBus integration for handling DBus events. 🚌
    2. Outloud is Easier To Install On 64-Bit Systems. ʕ
    3. Managing Shell Buffers across multiple projects. 📽
    4. EWW loads EBook settings when opening EPub files. 🕮
    5. Bash Utils for power users. 🐚
    6. Speech-Enabled Elisp-Refs. 🤞
    7. Updated C/C++ Mode Support. ䷢
    8. Updated EShell Support. ︹
    9. Speach-Enabled Clojure. 𝍏
    10. Speech-Enabled Geiser For Scheme Interaction. ♨
    11. Speech-Enabled Cider. 🍎
    12. Speech-Enable Racket IDE. ƛ
    13. Parameterized auditory icons using SoX-Gen. 🔊
    14. IHeart Radio wizard. 📻
    15. Speech-Enabled Projectile. 🢫
    16. Spoken notifications are cached in a special buffer. ⏰
    17. Flycheck And Interactive Correction. 𐄂

      • And a lot more than wil fit this margin. … 🗞

4 Establishing Liberty, Equality And Freedom:

Never a toy system, Emacspeak is voluntarily bundled with all
major Linux distributions. Though designed to be modular,
distributors have freely chosen to bundle the fully integrated
system without any undue pressure—a documented success for
the integrated innovation embodied by Emacspeak. As the system
evolves, both upgrades and downgrades continue to be available at
the same zero-cost to all users. The integrity of the Emacspeak
codebase is ensured by the reliable and secure Linux platform
used to develop and distribute the software.

Extensive studies have shown that thanks to these features, users
consider Emacspeak to be absolutely priceless. Thanks to this
wide-spread user demand, the present version remains priceless
as ever—it is being made available at the same zero-cost as
previous releases.

At the same time, Emacspeak continues to innovate in the area of
eyes-free Assistance and social interaction and carries forward the
well-established Open Source tradition of introducing user interface
features that eventually show up in luser environments.

On this theme, when once challenged by a proponent of a crash-prone
but well-marketed mousetrap with the assertion "Emacs is a system from
the 70's", the creator of Emacspeak evinced surprise at the unusual
candor manifest in the assertion that it would take popular
idiot-proven interfaces until the year 2070 to catch up to where the
Emacspeak audio desktop is today. Industry experts welcomed this
refreshing breath of Courage Certainty and Clarity (CCC) at a time
when users are reeling from the Fear Uncertainty and Doubt (FUD)
unleashed by complex software systems backed by even more convoluted
press releases.

5 Independent Test Results:

Independent test results have proven that unlike some modern (and
not so modern) software, Emacspeak can be safely uninstalled without
adversely affecting the continued performance of the computer. These
same tests also revealed that once uninstalled, the user stopped
functioning altogether. Speaking with Aster Labrador, the creator of
Emacspeak once pointed out that these results re-emphasize the
user-centric design of Emacspeak; "It is the user –and not the
computer– that stops functioning when Emacspeak is uninstalled!".

5.1 Note from Aster,Bubbles and Tilden:

UnDoctored Videos Inc. is looking for volunteers to star in a
video demonstrating such complete user failure.

6 Obtaining Emacspeak:

Emacspeak can be downloaded from GitHub –see you can visit Emacspeak on the
WWW at You can subscribe to the emacspeak
mailing list — — by sending mail to the
list request address The Emacspeak
is a good source for news about recent enhancements and how to
use them.

The latest development snapshot of Emacspeak is always available via
Git from GitHub at
Emacspeak GitHub .

7 History:

  • Emacspeak 46.0 (HelpfulDog) heralds the coming of Smart Assistants.
  • Emacspeak 45.0 (IdealDog) is named in recognition of Emacs'
    excellent integration with various programming language
    environments — thanks to this, Emacspeak is the IDE of choice
    for eyes-free software engineering.
  • Emacspeak 44.0 continues the steady pace of innovation on the
    audio desktop.
  • Emacspeak 43.0 brings even more end-user efficiency by leveraging the
    ability to spatially place multiple audio streams to provide timely
    auditory feedback.
  • Emacspeak 42.0 while moving to GitHub from Google Code continues to
    innovate in the areas of auditory user interfaces and efficient,
    light-weight Internet access.
  • Emacspeak 41.0 continues to improve
    on the desire to provide not just equal, but superior access —
    technology when correctly implemented can significantly enhance the
    human ability.
  • Emacspeak 40.0 goes back to Web basics by enabling
    efficient access to large amounts of readable Web content.
  • Emacspeak 39.0 continues the Emacspeak tradition of increasing the breadth of
    user tasks that are covered without introducing unnecessary
  • Emacspeak 38.0 is the latest in a series of award-winning
    releases from Emacspeak Inc.
  • Emacspeak 37.0 continues the tradition of
    delivering robust software as reflected by its code-name.
  • Emacspeak 36.0 enhances the audio desktop with many new tools including full
    EPub support — hence the name EPubDog.
  • Emacspeak 35.0 is all about
    teaching a new dog old tricks — and is aptly code-named HeadDog in
    on of our new Press/Analyst contact. emacspeak-34.0 (AKA Bubbles)
    established a new beach-head with respect to rapid task completion in
    an eyes-free environment.
  • Emacspeak-33.0 AKA StarDog brings
    unparalleled cloud access to the audio desktop.
  • Emacspeak 32.0 AKA
    LuckyDog continues to innovate via open technologies for better
  • Emacspeak 31.0 AKA TweetDog — adds tweeting to the Emacspeak
  • Emacspeak 30.0 AKA SocialDog brings the Social Web to the
    audio desktop—you cant but be social if you speak!
  • Emacspeak 29.0—AKAAbleDog—is a testament to the resilliance and innovation
    embodied by Open Source software—it would not exist without the
    thriving Emacs community that continues to ensure that Emacs remains
    one of the premier user environments despite perhaps also being one of
    the oldest.
  • Emacspeak 28.0—AKA PuppyDog—exemplifies the rapid pace of
    development evinced by Open Source software.
  • Emacspeak 27.0—AKA
    FastDog—is the latest in a sequence of upgrades that make previous
    releases obsolete and downgrades unnecessary.
  • Emacspeak 26—AKA
    LeadDog—continues the tradition of introducing innovative access
    solutions that are unfettered by the constraints inherent in
    traditional adaptive technologies.
  • Emacspeak 25 —AKA ActiveDog
    —re-activates open, unfettered access to online
  • Emacspeak-Alive —AKA LiveDog —enlivens open, unfettered
    information access with a series of live updates that once again
    demonstrate the power and agility of open source software
  • Emacspeak 23.0 — AKA Retriever—went the extra mile in
    fetching full access.
  • Emacspeak 22.0 —AKA GuideDog —helps users
    navigate the Web more effectively than ever before.
  • Emacspeak 21.0
    —AKA PlayDog —continued the
    Emacspeak tradition of relying on enhanced
    productivity to liberate users.
  • Emacspeak-20.0 —AKA LeapDog —continues
    the long established GNU/Emacs tradition of integrated innovation to
    create a pleasurable computing environment for eyes-free
  • emacspeak-19.0 –AKA WorkDog– is designed to enhance
    user productivity at work and leisure.
  • Emacspeak-18.0 –code named
    GoodDog– continued the Emacspeak tradition of enhancing user
    productivity and thereby reducing total cost of
  • Emacspeak-17.0 –code named HappyDog– enhances user
    productivity by exploiting today's evolving WWW
  • Emacspeak-16.0 –code named CleverDog– the follow-up to
    SmartDog– continued the tradition of working better, faster,
  • Emacspeak-15.0 –code named SmartDog–followed up on TopDog
    as the next in a continuing series of award-winning audio desktop
    releases from Emacspeak Inc.
  • Emacspeak-14.0 –code named TopDog–was

the first release of this millennium.

  • Emacspeak-13.0 –codenamed
    YellowLab– was the closing release of the
    20th. century.
  • Emacspeak-12.0 –code named GoldenDog– began
    leveraging the evolving semantic WWW to provide task-oriented speech
    access to Webformation.
  • Emacspeak-11.0 –code named Aster– went the
    final step in making Linux a zero-cost Internet access solution for
    blind and visually impaired users.
  • Emacspeak-10.0 –(AKA
    Emacspeak-2000) code named WonderDog– continued the tradition of
    award-winning software releases designed to make eyes-free computing a
    productive and pleasurable experience.
  • Emacspeak-9.0 –(AKA
    Emacspeak 99) code named BlackLab– continued to innovate in the areas
    of speech interaction and interactive accessibility.
  • Emacspeak-8.0 –(AKA Emacspeak-98++) code named BlackDog– was a major upgrade to
    the speech output extension to Emacs.
  • Emacspeak-95 (code named Illinois) was released as OpenSource on
    the Internet in May 1995 as the first complete speech interface
    to UNIX workstations. The subsequent release, Emacspeak-96 (code
    named Egypt) made available in May 1996 provided significant
    enhancements to the interface. Emacspeak-97 (Tennessee) went
    further in providing a true audio desktop. Emacspeak-98
    integrated Internetworking into all aspects of the audio desktop
    to provide the first fully interactive speech-enabled WebTop.

8 About Emacspeak:

Originally based at Cornell (NY) — —home to Auditory User
Interfaces (AUI) on the WWW, Emacspeak is now maintained on GitHub The system is mirrored
world-wide by an international network of software archives and
bundled voluntarily with all major Linux distributions. On Monday,
April 12, 1999, Emacspeak became part of the Smithsonian's Permanent
Research Collection
on Information Technology at the Smithsonian's
National Museum of American History.

The Emacspeak mailing list is archived at Vassar –the home of the
Emacspeak mailing list– thanks to Greg Priest-Dorman, and provides a
valuable knowledge base for new users.

9 Press/Analyst Contact: Tilden Labrador

Going forward, Tilden acknowledges his exclusive monopoly on
setting the direction of the Emacspeak Audio Desktop, and
promises to exercise this freedom to innovate and her resulting
power responsibly (as before) in the interest of all dogs.

*About This Release:

Windows-Free (WF) is a favorite battle-cry of The League Against
Forced Fenestration (LAFF). –see for details on
the ill-effects of Forced Fenestration.

CopyWrite )C( Aster, Hubbell and Tilden Labrador. All Writes Reserved.
HeadDog (DM), LiveDog (DM), GoldenDog (DM), BlackDog (DM) etc., are Registered
Dogmarks of Aster, Hubbell and Tilden Labrador. All other dogs belong to
their respective owners.

Saturday, April 22, 2017

Mail On The emacspeak Audio Desktop

Email On The Emacspeak Audio Desktop

1 Overview

This question comes up every few months on the emacspeak mailing
list. In general, see
Emacspeak Tools to quickly discover available speech-enabled
applications. This article outlines some of the available email setups
given the wide degree of variance in this space.

2 Background

How one puts together an email environment is a function of the

  1. How email is retrieved.
  2. How email is stored (if storing locally).
  3. How email is sent.

Here is an overview of what is available as viewed from the world of
Linux in general and Emacs in particular:

2.1 Email Retrieval

Email can be retrieved in a number of ways:

  • IMap via Emacs This is implemented well in GNUS, and poorly in
    Emacs/VM. Note that Emacs is single-threaded, and fetching large
    volumes of email via IMap is painful.
  • Batch Retrieval: IMap Tools like fetchmail, offlineimap and friends that live
    outside of Emacs can be used to batch-retrieve email in the
    background. The retrieved mail gets delivered locally as in the past.
  • Mail Filtering: UNIX procmail enables filtering of locally
    delivered email into separate folders for automatically organizing
    incoming email.

2.2 Sending Email

Sending email involves:

  1. Composing email — typically invoked via key-sequence C-x m
    (command: compose-mail). Emacs email packages implement
    specific versions of this command, e.g. vm-mail from package
    emacs/vm, message-mail from the message package etc.
  2. Sending email: This is specific to the email provider being used,
    e.g., GMail. In the past, UNIX machines could talk SMTP to
    the Mail Gateway, but this has mostly disappeared over time. For
    an example of how to configure Emacs to send email via GMail
    using SMTP , see file tvr/gm-smtp.el in the emacspeak repository.

2.3 Local Storage Format

  • UNIX Mail: An email folder is a file of messages. This
    format is used by clients like Emacs/VM, UNIX Mail etc.
  • Maildir: A mail folder is a directory, with
    individual email messages living in files of their
    own. Sample clients include MH-E (UNIX MH), MU4E.
  • RMail This is Emacs' original email format.

3 Putting It All Together

The next sections show my present email setup put together using the
building blocks described above.

  1. I use Linux on all my machines, and Android on my phone.
  2. I mostly limit email usage on my phone to get a quick overview of email that might require immediate attention — toward this end, I have a to-mobile GMail label that collects urgent messages.
  3. Linux is where I handle email in volume.
  4. I use my Inbox as

my ToDo list — which means that I leave little or no email in my
Inbox unless I'm on vacation and disconnected from email.

3.1 Desktop: Batch Retrieval And Emacs/VM

This is the email setup on my workstation. See next section for the
email setup while mobile.

  1. I batch-retrieve email using fetchmail.
  2. This email gets filtered through procmail and auto-filed into
    several folders based on a set of procmail rules. Typical rules
    include separating out various email lists into their respective folders.
  3. Note that this does not preclude using IMap via GNUS to read
    email while online.
  4. Email that is not filtered into separate folders e.g. email that
    is sent directly to me, email regarding projects that need
    immediate attention etc., land up in folder ~/mbox.
  5. So when I launch emacs/vm on my desktop, the above is all I
    need to deal with at any given moment.
  6. I typically read Auto-filed mailing lists using emacs/vm about once a day or
    less — I use package mspools to get a quick overview of the
    state of those mail folders.

3.2 Mobile AccessOn Laptop: GNUS And IMap

See gnus-prepare.el for my gnus configuration for accessing GMail
via imap. That configuration is setup to access multiple GMail accounts.

  1. I see each GMail label as a separate group in GNUS.
  2. I only sync high-priority labels — this works well even
    over slow WIFI connections while on the road. As an example, the
    afore-mentioned to-mobile GMail label is a high-priority group.
  3. Module gm-nnir defines a GNUS/GMail extension that enables
    one to search GMail using GMail's search operators — that is my
    prefered means of quickly finding email messages using
    search. This is very fast since the search happens server-side,
    and only email headers are retrieved when displaying the search
  4. Note that this solution is not laptop/mobile specific — I use
    this setup for searching GMail from my desktop as well.

3.3 Composing And Sending EMail

  1. I use compose-mail to compose email.
  2. I optionally activate orgtbl-mode and/or orgstruct-mode if
    editing structured content within the email body.
  3. I send email out using the setup in gm-smtp.el.

4 Conclusion

  1. Email in Linux/Emacs is composed of a set of
    independent building blocks — this gives maximal flexibility.
  2. That flexibility allows one to put together different email
    workflows depending on the connectivity environment in use.

Wednesday, March 01, 2017

Emacs: Check Interactive Call For Emacspeak

Emacs: Check Interactive Call For Emacspeak

1 Background

Emacspeak uses advice as the means to speech-enable Emacs.
Emacspeak's advice forms need to check if the function being
speech-enabled is being called interactively — otherwise one would
get a lot of chatter as these functions get called from within elisp
programs, e.g. functions like forward-sexp or kill-sexp, that play
the dual role of both an interactive command, as well as a convenient
elisp function.

Until Emacs 24, the solution used was to write code that did the
following check:

(when (interactive-p) ...

In Emacs-24, interactive-p was made obsolete and replaced with

(called-interactively-p 'interactive)

Emacspeak initially used the above form to perform the equivalent
check. However, around the same time, Emacs' advice implementation
went through some changes, and there was an attempt to replace
advice.el with nadvice.el.

At the end of that round of changes, some problems emerged with the
new called-interactively-p implementation; specifically, calling
:called-interactively-p_ within around advice forms resulted in hard
to debug errors, including one case of infinite recursion involving
library smie.el when invoked from within ruby-mode.

After studying the problem in depth in 2014, I decided to create an
Emacspeak-specific implementation of the is-interactive check.

The resulting implementation has worked well for the last 30 months;
this article is here mostly to document how it works, and the reason
for its existence. Note that Emacspeak uses this custom predicate
only within advice forms. Further, this predicate has been coded
to only work within advice forms created by emacspeak. This
constraint can likely be relaxed, but the tighter implementation is
less risky.

2 Implementation — ems-interactive-p

2.1 Overview

Within an advice forms defined by Emacspeak, detect if the enclosing
function call is the result of explicit user interaction, i.e. by
pressing a key, or via an explicit call to
call-interactively. Emacspeak produces auditory feedback only if
this predicate returns t.

We first introduce a flag that will be used to record if the enclosing
(containing) function has an Emacspeak-defined advice on it and is
called interactively — these are the only cases that our predicate
needs to test.

(defvar ems-called-interactively-p nil
  "Flag that records if containing function was called interactively."

Next, we define a function that checks if interactive calls to a
function should be recorded. We're only interested in functions that
have an advice form defined by Emacspeak — all Emacspeak-defined
advice forms have the name emacspeak.

(defun ems-record-interactive-p (f)
  "Predicate to test if we need to record interactive calls of
this function. Memoizes result for future use by placing a
property 'emacspeak on the function symbol."
   ((not (symbolp f)) nil)
   ((get f 'emacspeak) t) ; already memoized
   ((ad-find-some-advice f 'any  "emacspeak") ; there is an emacspeak advice
    (put f 'emacspeak t)) ; memoize for future and return true
   (t nil)))

This is a memoized function that remembers earlier invocations by
setting property emacspeak on the function symbol.

All advice forms created by Emacspeak are named emacspeak, so we
can test for the presence of such advice forms using the test:

(ad-find-some-advice f 'any  "emacspeak")

If this test returns T, we memoize the result and return it.

Next, we advice function call-interactively to check
if the function being called interactively is one of the functions
that has been adviced by Emacspeak. If so, we record the fact in the
previously declared global flag

(defadvice call-interactively (around emacspeak  pre act comp)
  "Set emacspeak  interactive flag if there is an Emacspeak advice 
on the function being called."
  (let ((ems-called-interactively-p ems-called-interactively-p)) ; preserve enclosing state
    (when (ems-record-interactive-p (ad-get-arg 0))
      (setq ems-called-interactively-p (ad-get-arg 0)))

We define an equivalent advice form on function
funcall-interactively as well. Now, whenever any function that has
been adviced by Emacspeak is called interactively, that interactive
call gets recorded in the global flag. In the custom Emacspeak
predicate we define, we check the value of this flag, and if
set, consume it, i.e. unset the flag and return T.

(defsubst ems-interactive-p ()
  "Check our interactive flag.
Return T if set and we are called from the advice for the current
interactive command. Turn off the flag once used."
  (when ems-called-interactively-p                 ; interactive call
    (let ((caller (cl-second (backtrace-frame 1))) ; name of containing function
          (caller-advice  ;advice generated wrapper
           (ad-get-advice-info-field ems-called-interactively-p  'advicefunname))
          (result nil))
      (setq result
            (or (eq caller caller-advice) ; called from our advice
                (eq ems-called-interactively-p caller))) ; called from advice wrapper
      (when result
        (setq ems-called-interactively-p nil) ; turn off now that we used  it

The only fragile part of the above predicate is the call to
backtrace-frame which we use to discover the name of the enclosing
function. Notice however that this is no more fragile than the current
implementation of called-interactively-p — which also uses
backtrace-frame; If there are changes in the byte-compiler, this
form may need to be updated. The implementation above has the
advantage of working correctly for Emacspeak's specific use-case.

Friday, February 10, 2017

Audio Deja Vu: Audio Formatted Math On The Emacspeak Desktop

Audio Deja Vu: Audio Formatted Math On The Emacspeak Desktop

1 Overview

This article previews a new feature in the next Emacspeak release —
audio-formatted Mathematics using Aural CSS. Volker Sorge worked
at Google as a Visiting Scientist from Sep 2012 to August 2013, when
we implemented math
access in ChromeVox
— see this brief overview. Since leaving
Google, Volker has refactored and extended his work to create an Open
Source Speech-Rule-Engine implemented using NodeJS. This
speech-rule-engine can be used in many different environments;
Emacspeak leverages that work to enable audio-formatting and
interactive browsing of math content.

2 Overview Of Functionality

Math access on the Emacspeak desktop is implemented via module
emacspeak-maths.el — see js/node/ in the Emacspeak GitHub
repository for setup instructions.

Once loaded, module emacspeak-maths provides a Math Navigator that
implements the user interface for sending Math expressions to the
Speech-Rule-Engine, and for interactively browsing the resulting
structure. At each step of the interaction, Emacspeak receives math
expressions that have been annotated with Aural CSS and produces
audio-formatted output. The audio-formatted text can itself be
navigated in a special Spoken Math emacs buffer.

Module emacspeak-maths.el implements various affordances for
dispatching mathematical content to the Speech-Rule-Engine — see
usage examples in the next section.

3 Usage Examples

3.1 The Emacspeak Maths Navigator

  • The maths navigator can be invoked by pressing S-SPC (hold
    down Windows key and press SPC) — this runs the command emacspeak-maths-navigator/body.
  • Once invoked, the /Maths Navigator can be used to enter an
    expression to read.
  • Pressing SPC again prompts for the LaTeX math expression.
  • Pressing RET guesses the expression to read from the current context.
  • The arrow keys navigate the expression being read.
  • Pressing o switches to the Spoken Math buffer and exits the

See the relevant chapter in the online Emacspeak manual for details.

3.2 Math Content In LaTeX Documents

  1. Open a LaTeX document containing math content.
  2. Move point to a line containing mathematical markup.
  3. Press S-SPC RET to have that expression audio-formatted.
  4. Use arrow keys to navigate the resulting structure.
  5. Press any other key to exit the navigator.

3.3 Math Content On Wikipedia

  1. Open a Wikipedia page in the Emacs Web Wowser (EWW) that has
    mathematical content.
  2. Wikipedia displays math as images, with the alt-text giving the
    LaTeX representation.
  3. Navigate to some math content on the page, then press S-SPC
    a to speak that content — a is for alt.
  4. As an example, navigate to Wikipedia Math Example, locate math expressions on that page, then
    press S-SPC a.

3.4 Math Content From The Emacs Calculator

  1. The built-in Emacs Calculator (calc) provides many complex
    math functions including symbolic algebra.
  2. For my personal calc setup, see tvr/calc-prepare.el in the
    Emacspeak GitHub repo.
  3. This setting below sets up the Emacs Calculator to output results
    as LaTeX: (setq calc-language 'tex)
  4. With the above setting in effect, launch the emacs Calculator by
    pressing M-##.
  5. Press ' — to use algebraic mode — and enter sin(x).
  6. Press a t to get the Taylor series expansion of the above
    expression, and press x when prompted for the variable.
  7. This displays the Taylor Series expansion up to the desired
    number of terms — try 7 terms.
  8. Now, with Calc having shown the results as TeX, press S-SPC
    RET to browse this expression using the Maths Navigator.

4 And The Best Is Yet To Come

This is intentionally called an early preview because there is still
much that can be improved:

  1. Enhance the rule engine to infer and convey more semantics.
  2. Improved audio formatting rules to better present the available information.
  3. Update/tune the use of Aural CSS properties to best leverage
    today's TTS engines.
  4. Integrate math-reading functionality into more usage contexts in
    addition to the ones enumerated in this article.

5 References

  1. Youtube Video from early 2013 demonstrating Math Access in Chrome
  2. AllThings Digital outlining math access — published June 2013.
  3. Assets 2016 publication describing this work.
  4. js/node/aster-math-examples.tex Collection of math examples in
    LaTeX from AsTeR. Used to progressively improve speech-rules and
    the resulting audio-formatted output
  5. Speech-Rule-Engine on github.
  6. Speech-Rule-Engine in action: Accessible Maths in all browsers

Date: 2017-02-08 Wed 00:00

Author: T.V Raman

Wednesday, January 04, 2017

Fun With TTS (Voxin) And Ladspa

Fun With TTS (Voxin) And Ladspa

1 Executive Summary

Voxin 1.6 — AKA ViaVoice Outloud — no longer requires that the
Emacspeak TTS server be built as a 32-bit binary. This means that
installing Voxin on 64-bit systems is now significantly easier since
you no longer need to install 32-bit versions of TCL, TCLX, and the
dependencies needed by library In addition to
easing the installation process, not needing 32-bit binaries means
that the Emacspeak Outloud server can now take advantage of audio
processing such as that provided by LADSPA.

2 Going 64-Bit: Upgrading To Voxin 1.6

  1. Install Voxin-1.6 or later from Voxin.
  2. Update Emacspeak from GitHub (this will be part of the next
    public release).
  3. Rebuild the binary in the servers/linux-outloud
cd servers/linux-outloud && make clean && make

If all goes well, you'll now have a 64-bit version of
You can now run the Outloud server as servers/outloud.
In about a year's time, servers/32-outloud will move to
servers/obsolete, as will the associated servers/32-speech-server
and servers/ssh-32-outloud.

3 Applying LADSPA Effects Processing To TTS

With a 64-bit build of in place, we can now call on
installed LADSPA plugins to apply digital sound processing to TTS
output. To experiment with the possibilities, see some of the
virtual sound devices defined in servers/linux-outloud/asoundrc.
Copy over that file to your ~/.asoundrc after updating it to match
your sound setup — you'll likely need to change the default
sound-card to match your setup.
You can now set environment variable ALSA_DEFAULT to one of the
tts_<effect> virtual devices — and have the Outloud server apply
the specified LADSPA effect to the generated TTS. Here is an example:

cd servers 
(export ALSA_DEFAULT=tts_reverb; ./outloud)

4 The Best Is Yet To Come …

The possibilities are endless — ALSA with LADSPA provides a rich
suite of audio processing possibilities.

5 Acknowledgements

I'd like to acknowledge Gilles Casse for his work over the years on
ensuring that Linux users have access to good quality TTS. Outloud
would have been dead a long time ago if it weren't for his continued
efforts toward keeping the lights on. His newest creation, libvoxin
that forms the crux of Voxin-1.6 is an excellent piece of engineering
that is likely to help Outloud survive for the future on modern Linux
distros. Note that Gilles is also the primary author of the Emacspeak
ESpeak server.