gstlal_play

#!/usr/bin/env python
#
# Copyright (C) 2011--2013  Kipp Cannon, Chad Hanna, Drew Keppel
#
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the
# Free Software Foundation; either version 2 of the License, or (at your
# option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
# Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.


from optparse import OptionParser
import sys

import gi
gi.require_version('Gst', '1.0')
from gi.repository import GObject, Gst
GObject.threads_init()
Gst.init(None)

import lal

from glue.ligolw import utils as ligolw_utils
from gstlal import datasource
from gstlal import multirate_datasource
from gstlal import pipeparts
from gstlal import simplehandler
from glue.ligolw.utils import segments as ligolw_segments
from glue.ligolw import lsctables, ligolw

### This program will play data in a variety of ways
###
### This program will play data in a variety of ways.  Its input is anything
### supported by :any:`datasource`.  You can additionally whiten the data
### or apply a band pass filtering.  It can direct its output to either your
### sound card, various audio file formats, or stderr/stdout in tab delimited
### ASCII text.
###
### Graph of the gsreamer pipeline
### ------------------------------
###
### - gray boxes are optional and depend on the command line given
###
### .. graphviz::
###
###    digraph G {
###    // graph properties
###
###    rankdir=LR;
###    compound=true;
###    node [shape=record fontsize=10 fontname="Verdana"];
###    edge [fontsize=8 fontname="Verdana"];
###
###    // nodes
###
###    "mkbasicsrc()" [URL="\ref datasource.mkbasicsrc()"];
###    "whitened_multirate_src()" [label="whitened_multirate_src()", URL="\ref multirate_datasource.mkwhitened_multirate_src()", style=filled, color=lightgrey];
###    "mkresample()" [URL="\ref pipeparts.mkresample()", style=filled, color=lightgrey];
###    "mkcapsfilter()" [URL="\ref pipeparts.mkcapsfilter()", style=filled, color=lightgrey];
###    "mkaudiochebband()" [URL="\ref pipeparts.mkaudiochebband()", style=filled, color=lightgrey];
###    "mkaudiocheblimit()" [URL="\ref pipeparts.mkaudiocheblimit()", style=filled, color=lightgrey];
###    "mkaudioconvert()" [URL="\ref pipeparts.mkaudioconvert()"];
###    "mkaudioamplify()" [URL="\ref pipeparts.mkaudioamplify()"];
###    "mkautoaudiosink()" [URL="\ref pipeparts.mkautoaudiosink()", style=filled, color=lightgrey];
###    "mkwavenc()" [URL="\ref pipeparts.mkwavenc()", style=filled, color=lightgrey];
###    "mkflacenc()" [URL="\ref pipeparts.mkflacenc()", style=filled, color=lightgrey];
###    "mkvorbisenc()" [URL="\ref pipeparts.mkvorbisenc()", style=filled, color=lightgrey];
###    "mkfilesink()" [URL="\ref pipeparts.mkfilesink()", style=filled, color=lightgrey];
###    "mknxydumpsink()" [URL="\ref pipeparts.mknxydumpsink()", style=filled, color=lightgrey];
###
###    // connections
###
###    "mkbasicsrc()" -> "mkresample()" [label=" --whiten not provided"];
###    "mkresample()" -> "mkcapsfilter()";
###    "mkcapsfilter()" -> "mkaudioconvert()" [label=" neither --low-pass-filter nor --high-pass-filter provided"];
###    "mkcapsfilter()" -> "mkaudiochebband()" [label=" --low-pass-filter and --high-pass-filter provided"];
###    "mkcapsfilter()" -> "mkaudiocheblimit()" [label=" --low-pass-filter or --high-pass-filter provided"];
###
###    "mkbasicsrc()" -> "whitened_multirate_src()" [label=" --whiten provided"];
###    "whitened_multirate_src()" -> "mkaudioconvert()" [label=" neither --low-pass-filter nor --high-pass-filter provided"];
###    "whitened_multirate_src()" -> "mkaudiochebband()" [label=" --low-pass-filter and --high-pass-filter provided"];
###    "whitened_multirate_src()" -> "mkaudiocheblimit()" [label=" --low-pass-filter or --high-pass-filter provided"];
###
###    "mkaudiochebband()" -> "mkaudioconvert()";
###    "mkaudiocheblimit()" -> "mkaudioconvert()";
###
###    "mkaudioconvert()" -> "mkaudioamplify()";
###
###    "mkaudioamplify()" -> "mkautoaudiosink()" [label=" --output not provided"];
###    "mkaudioamplify()" -> "mkwavenc()" [label=" --output ends with '.wav'"];
###    "mkaudioamplify()" -> "mkflacenc()" [label=" --output ends with '.flac'"];
###    "mkaudioamplify()" -> "mkvorbisenc()" [label=" --output ends with '.ogg'"];
###    "mkaudioamplify()" -> "mknxydumpsink()" [label=" --output ends with '.txt' or is /dev/stderr or /dev/stdout"];
###    "mkwavenc()" -> "mkfilesink()";
###    "mkvorbisenc()" -> "mkfilesink()";
###    "mkflacenc()" -> "mkfilesink()";
###   }
###
### Usage cases
### -----------
###
### See :py:func:`datasource.append_options` for additional usage cases for datasource specific command line options
###
### 1. Viewing low latency data in stdout (e.g. on CIT cluster) Note ctrl+c kills this::
###
###    $ gstlal_play --data-source framexmit --channel-name=L1=FAKE-STRAIN  \
###    --output /dev/stdout
###
### 2. Pipe low latency data to an ogg file narrowing in on the sweet spot and
### add amplification to make it audible.  Note ctrl+c kills this::
###
###    $ gstlal_play --data-source framexmit --channel-name=L1=FAKE-STRAIN  \
###    --high-pass-filter 40 --low-pass-filter 1000 --amplification 1e21 --output test.ogg
###
### 3. Write injection time series from an xml file into an ASCII delimited text file::
###
###    $ gstlal_play --data-source silence --gps-start-time 966383960 \
###    --gps-end-time 966384960 --channel-name=L1=FAKE-STRAIN  \
###    --injections=BNS-MDC1-FIXEDMASS.xml --output test.txt
###
### 4. Other things are certainly possible.  Please add some!
###


@lsctables.use_in
class LIGOLWContentHandler(ligolw.LIGOLWContentHandler):
   pass


def parse_command_line():

   parser = OptionParser(description = __doc__)

   #
   # First append the datasource common options
   #

   datasource.append_options(parser)

   parser.add_option("--output", metavar = "filename", help = "Set the filename in which to save the output.  If not given, output is sent to the default audio device.  The filename's extension determines the format, the following are recognized:  .wav, .flac, .ogg, .txt, /dev/stdout, /dev/stderr")
   parser.add_option("--sample-format", metavar = "name", help = "Force a specific sample format for the output.  If not specified, the format is chosen by auto-negotiation with the encoder.  Allowed values are any GStreamer-recognized format that is compatible with the requested encoder.  Examples include \"F32LE\", \"F64LE\".")
   parser.add_option("--rate", metavar = "Hz", type = "int", default = 4096, help = "Downsample input to this sample rate. Default = 4096 Hz.  Must be <= input sample rate or else you will get a caps negotiation error.")
   parser.add_option("--whiten", action = "store_true", help = "Whiten the time series (default = do not whiten).")
   parser.add_option("--veto-segments-file", metavar = "filename", help = "Set the name of the LIGO light-weight XML file from which to load vetoes (optional). Must coincide with --whiten")
   parser.add_option("--veto-segments-name", metavar = "name", help = "Set the name of the segments to extract from the segment tables and use as the veto list.  Must coincide with --whiten", default = "vetoes")
   parser.add_option("--reference-psd", metavar = "file", help = "When whitening, normalize the time series to the spectrum described in this XML file.  If this option is not given, the spectrum is measured from the data.") 
   parser.add_option("--low-pass-filter", metavar = "Hz", type = "float", help = "Low pass filter frequency (default = no low-pass filter).  Low-pass filter is applied after whitening.")
   parser.add_option("--high-pass-filter", metavar = "Hz", type = "float", help = "High pass filter frequency (default = no high-pass filter).  High-pass filter is applied after whitening.")
   parser.add_option("--amplification", metavar = "num", type = "float", default = 1.0, help = "Amplify the timeseries this much (default = no amplification).  Amplification is applied after low- and high-pass filtering. For unwhitened h(t) that is bandpassed to the most sensitive region you might need to set this to 1e20 to make it audible")
   parser.add_option("-v", "--verbose", action = "store_true", help = "Be verbose.")

   #
   # parse the arguments and sanity check
   #

   options, filenames = parser.parse_args()

   if options.low_pass_filter is not None and options.high_pass_filter is not None:
       if options.low_pass_filter <= options.high_pass_filter:
           raise ValueError("--low-pass-filter must be > --high-pass-filter")

   if options.reference_psd or options.veto_segments_file and not options.whiten:
       raise ValueError("--reference-psd and --veto-segments-file requires --whiten")

   if len(options.channel_name) > 1:
       raise ValueError("only one --channel-name allowed")

   return options, filenames


# parsing and setting up some core structures
options, filenames = parse_command_line()

gw_data_source_info = datasource.GWDataSourceInfo(options)
instrument, = gw_data_source_info.channel_dict

if options.reference_psd is not None:
   psd = lal.series.read_psd_xmldoc(ligolw_utils.load_filename(options.reference_psd, verbose = options.verbose, contenthandler = lal.series.PSDContentHandler))[instrument]
else:
   psd = None

if options.veto_segments_file is not None:
   veto_segments = ligolw_segments.segmenttable_get_by_name(ligolw_utils.load_filename(options.veto_segments_file, verbose = options.verbose, contenthandler = LIGOLWContentHandler), options.veto_segments_name).coalesce()[instrument]
else:
   veto_segments = None

# building the event loop and pipeline
mainloop = GObject.MainLoop()
pipeline = Gst.Pipeline("gstlal_play")
handler = simplehandler.Handler(mainloop, pipeline)

#
# the pipeline
#
# A basic src
head, _, _ = datasource.mkbasicsrc(pipeline, gw_data_source_info, instrument, verbose = options.verbose)

# if whitening, leverage mkwhitened_multirate_src() otherwise just resample
if options.whiten:
   head = multirate_datasource.mkwhitened_multirate_src(pipeline, head, [options.rate], instrument, psd, track_psd = True, veto_segments = veto_segments)[options.rate]
else:
   head = pipeparts.mkresample(pipeline, head, quality = 9)
   head = pipeparts.mkcapsfilter(pipeline, head, "audio/x-raw, rate=%d" % options.rate)

# handle filtering
if options.high_pass_filter is not None and options.low_pass_filter is not None:
   head = pipeparts.mkaudiochebband(pipeline, head, lower_frequency = options.high_pass_filter, upper_frequency = options.low_pass_filter)
elif options.high_pass_filter is not None:
   head = pipeparts.mkaudiocheblimit(pipeline, head, cutoff = options.high_pass_filter, mode = "high-pass")
elif options.low_pass_filter is not None:
   head = pipeparts.mkaudiocheblimit(pipeline, head, cutoff = options.low_pass_filter, mode = "low-pass")

# necessary audio convert and amplify 
head = pipeparts.mkaudioconvert(pipeline, pipeparts.mkaudioamplify(pipeline, head, options.amplification))
if options.sample_format is not None:
   head = pipeparts.mkcapsfilter(pipeline, head, "audio/x-raw, format=%s" % options.sample_format)

if options.output is None:
   pipeparts.mkautoaudiosink(pipeline, head)
elif options.output.endswith(".wav"):
   pipeparts.mkfilesink(pipeline, pipeparts.mkwavenc(pipeline, head), options.output)
elif options.output.endswith(".flac"):
   pipeparts.mkfilesink(pipeline, pipeparts.mkflacenc(pipeline, head), options.output)
elif options.output.endswith(".ogg"):
   head = pipeparts.mkoggmux(pipeline, pipeparts.mkvorbisenc(pipeline, head))
   pipeparts.mkfilesink(pipeline, head, options.output)
elif options.output.endswith(".txt") or options.output in ("/dev/stdout", "/dev/stderr"):
   pipeparts.mknxydumpsink(pipeline, head, options.output)
else:
   raise ValueError("unrecognized format for --output")

# Allow Ctrl+C or sig term to gracefully shut down the program for online
# sources, otherwise it will just kill it
if gw_data_source_info.data_source in ("lvshm", "framexmit"):# what about nds online?
   simplehandler.OneTimeSignalHandler(pipeline)

# Seek
if pipeline.set_state(Gst.State.READY) == Gst.StateChangeReturn.FAILURE:
   raise RuntimeError("pipeline failed to enter READY state")
if gw_data_source_info.data_source not in ("lvshm", "framexmit"):# what about nds online?
   datasource.pipeline_seek_for_gps(pipeline, gw_data_source_info.seg[0], gw_data_source_info.seg[1])

# run
if pipeline.set_state(Gst.State.PLAYING) == Gst.StateChangeReturn.FAILURE:
   raise RuntimeError("pipeline failed to enter PLAYING state")
mainloop.run()