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