GNOME Media 0.3.0 - internet radio, photographs and recordings on one map
==========================================================================

gnome-media has two pages, switched from the header bar.

Map: three layers of markers on a single OpenStreetMap:

  * radio stations, placed in the cities they broadcast from
    (from GNOME Radio 85.0.1: the station list and its GStreamer playback)
  * photographs, placed where they were taken, from the GPS position in
    their EXIF data (from gPhoto 3.0.1: the libgphoto2 camera layer and
    the picture viewer)
  * your Voicegram recordings, placed where they were made

Click a station marker to listen.  Where several stations share a city
(Oslo has 15) the marker shows a count and opens a menu.  Open a folder
of pictures (Ctrl+O) or import from a camera (Ctrl+Shift+C); every
picture with a GPS position appears as an orange dot; click it to select
the picture, double-click a thumbnail to open the viewer.  The search box
filters the station list and the map together.

Studio: a multitrack recorder with the recording features of GarageJam
8.0.1 (see below).


Recording
---------

Studio page (all GarageJam 8.0.1 recording features):

  * Press Record (Ctrl+R).  If no track is armed, a new track is created
    and the take is recorded into it.  Existing tracks play while you
    record, so you can overdub part by part.
  * Arm a different track with its red button to record a new take into
    it (one track is armed at a time).  Each take is kept as its own
    16-bit PCM WAV file; the track points at the latest one.
  * Volume, pan, mute (M) and solo (S) work live while playing.
  * Waveforms for every take, redrawn live while recording; click one to
    move the playhead.  Ctrl+Space plays and stops; pressing Stop twice
    returns to the start.
  * Input and output peak meters.
  * Import Audio (Ctrl+I) adds tracks from any file GStreamer can decode;
    Export Mixdown (Ctrl+E) renders a 16-bit PCM WAV, also headless:

        gnome-media --export-mixdown=myjam.gjxml --output=myjam.wav

  * Jams are saved as GarageJam XML (.gjxml, see doc/gjxml.md) and open
    in GarageJam 8.0.1, and the other way round.  Numbers are written
    locale-independently.  Takes for an unsaved jam go to
    ~/Music/GarageJam/Jam-<date>/; after saving, new takes are recorded
    next to the .gjxml file, and track files inside the project folder
    are stored with relative paths, so the folder can be moved as a whole.
  * Unsaved changes are asked about before New, Open and closing.

  Known limitations (as in GarageJam 8.0.1): recording always starts from
  the beginning of the timeline, and there is no automatic latency
  compensation for overdubs.

Voicegram Recording 1.0 (header bar microphone, or Ctrl+Shift+R):

  * Records the default audio input as Ogg Vorbis at 44,100 Hz into
    $HOME/Music/GNOME.ogg (G_USER_DIRECTORY_MUSIC) and writes
    $HOME/Music/GNOME.voice next to it, "GNOME" being the label; you can
    choose another label.  An existing pair is only replaced after you
    confirm, and only once the new recording has finished (it is written
    to LABEL.ogg.part first).
  * The .voice file is the specification's XML (doc/voicegram.md):

        <?xml version="1.0"?>
        <voice version="0.3.0">
          <station name="Ole Aamot" uri="https://www.example.org/">
            <location lat="59.9139000" lon="10.7522000">Oslo, Norway</location>
            <stream>http://stream.example.org:8000/GNOME.ogg</stream>
          </station>
        </voice>

    The station name is you (g_get_real_name() by default), uri your web
    site, location where you recorded (the map centre, named after the
    nearest place in the gazetteer) and each <stream> a URL where the
    recording can be listened to; several are allowed.
  * Starting values come from PREFIX/share/gnome-media/voicegram.xml; the
    values you used are kept in ~/.local/share/gnome-media/voicegram.xml.
  * The Ogg file is tagged too: title (label), artist (your name), album
    "Voicegram", date, place and web site.
  * Every LABEL.voice in the Music folder is listed in the Voicegrams tab
    and, if it has a place, shown as a green marker; activate it to play.
  * Voicegrams stay on your computer; nothing is uploaded.


What came from where
--------------------

  src/camera.c, camera.h, gphoto.h   gPhoto 3.0.1, plus one new function,
                                     gphoto_camera_get_exif()
  src/viewer.c, viewer.h             gPhoto 3.0.1, unchanged
  src/gm-project.[ch]                GarageJam 8.0.1 gj-project (GJXML)
  src/gm-engine.[ch]                 GarageJam 8.0.1 gj-engine, plus the
                                     Ogg Vorbis Voicegram pipeline
  src/gm-wav.[ch], gm-waveform.[ch]  GarageJam 8.0.1 gj-waveform, the
                                     widget ported from GTK 4 to GTK 3
  src/gm-studio.[ch]                 GarageJam 8.0.1 gj-window and main
                                     (mixdown), rebuilt as a GTK 3 page
  data/stations.xml, stations.dtd    GNOME Radio 85.0.1, unchanged
  data/gazetteer.tsv                 coordinates from GNOME Radio's marker
                                     table, extended and corrected (below)
  doc/gjxml.md, tests/data/sample.gjxml, examples/demo.gjxml
                                     GarageJam 8.0.1

  New: gm-exif (EXIF GPS/time reader), gm-station (station list parser),
  gm-places (gazetteer, grouping, nearest place), gm-player (GStreamer
  playbin), gm-voicegram (Voicegram Recording 1.0 documents), gm-voice
  (the Voicegram recorder), gm-window (the window), main.

Not carried over: GNOME Radio's three duplicated code generations
(gnome-radio-*, gtk-radio-*, gtk-internet-radio-locator-*), goocanvas,
geoclue and the deprecated gst-player API; gPhoto's own window,
command-line mode and HTML gallery; GarageJam's libadwaita interface
(gnome-media stays on GTK 3 because of libchamplain and gPhoto's viewer).

The map uses libchamplain 0.12 and GTK 3, as both upstream programs do.
Both are in maintenance mode; moving to libshumate and GTK 4 is the
obvious next step, but gPhoto's viewer is GTK 3 and was reused as is.


Station positions
-----------------

The station list has no coordinates; GNOME Radio placed markers from a
table hard-coded in C.  gnome-media reads those 104 positions, adds 85
approximate city/regional centres for locations the table did not cover,
and corrects seven that contradicted their own labels (e.g. "Kyiv" was
placed near Dnipro, "Dubai" at Mecca, "Troms" off the Trondheim coast,
"Brooklyn" on top of the Bronx).  tools/make-gazetteer.py regenerates the
file and lists every change.  The 255 entries in the database are 250
distinct stations (five are listed once per location and are merged);
245 of those are placed.  The other five (the RFA language services
"China, Asia" and similar, and "Space") are in the list but not on the map.

Add or fix places in ~/.local/share/gnome-media/gazetteer.tsv
(latitude TAB longitude TAB name); it overrides the system file.  Extra
stations go in ~/.local/share/gnome-media/stations.xml.


Building
--------

  meson setup build --prefix=/usr
  meson compile -C build
  meson test -C build
  sudo meson install -C build

Requires: GLib 2.68, GTK+ 3.22, libchamplain 0.12 (champlain-0.12 and
champlain-gtk-0.12), clutter-gtk 1.0, GStreamer 1.14 with the base and
good plugin sets (audiomixer, audiopanorama, level, wavenc, vorbisenc,
oggmux, autoaudiosrc/sink; add -bad/-ugly for some stations),
libgphoto2 2.5.

To run from the source tree:  GNOME_MEDIA_DATA_DIR=$PWD/data build/gnome-media [FOLDER]

The GLib-only core and its tests need nothing else:

  tests/run-tests.sh


Status - read this
------------------

Verified: gm-exif, gm-station, gm-places, gm-project (GJXML), gm-wav (WAV
peaks) and gm-voicegram (Voicegram Recording 1.0), and the data they
read, have 65 unit tests, run under AddressSanitizer and
UndefinedBehaviorSanitizer and through meson.  They include truncation
of every fixture at every length, random corruption and garbage, the
example document of the Voicegram specification, GarageJam's own GJXML
sample, and number formatting under a Norwegian (decimal comma) locale.

Checked but NOT run: every file in src/, including gm-engine,
gm-studio, gm-voice, gm-waveform, gm-window and main, compiles without
errors or warnings (gcc -fsyntax-only -Wall -Wextra -Wshadow
-Wno-unused-parameter -Werror) against the GTK 3.24, GStreamer 1.24 and
libgphoto2 headers, and meson.build configures and runs the tests; libchamplain and Clutter were not available, so their calls
were checked against declarations written from the 0.12 API only.
Nothing was linked or run with a display, an audio device or a camera:
treat recording, overdub timing, live mixing, export, the Voicegram
recorder and the map markers as untested until the first real build.


Licence
-------

The files taken from GarageJam 8.0.1 (gm-engine, gm-project, gm-studio,
gm-wav, gm-waveform and test-project) are GPL-3.0-or-later, so the
program as a whole is distributed under the GNU General Public License,
version 3 or later; see COPYING.GPL-3.  All other files remain under
version 2 or (at your option) any later version; see COPYING.
OpenStreetMap map data (c) OpenStreetMap contributors, shown under the
map by libchamplain.
