class_docstr: Reads raw audio data from any audio file that Gstreamer
  knows how to decode.
  
      >>> with GstAudioFile('something.mp3') as f:
      >>>     print f.samplerate
      >>>     print f.channels
      >>>     print f.duration
      >>>     for block in f:
      >>>         do_something(block)
  
  Iterating the object yields blocks of 16-bit PCM data. Three
  pieces of stream information are also available: samplerate (in Hz),
  number of channels, and duration (in seconds).
  
  It's very important that the client call close() when it's done
  with the object. Otherwise, the program is likely to hang on exit.
  Alternatively, of course, one can just use the file as a context
  manager, as shown above.
class_docstr_tok: ["Reads","raw","audio","data","from","any","audio","file","that","Gstreamer","knows","how","to","decode",".",">",">",">","with","GstAudioFile","(","'something.mp3","'",")","as","f",":",">",">",">","print","f.samplerate",">",">",">","print","f.channels",">",">",">","print","f.duration",">",">",">","for","block","in","f",":",">",">",">","do_something","(","block",")","Iterating","the","object","yields","blocks","of","16-bit","PCM","data",".","Three","pieces","of","stream","information","are","also","available",":","samplerate","(","in","Hz",")",",","number","of","channels",",","and","duration","(","in","seconds",")",".","It","'s","very","important","that","the","client","call","close","(",")","when","it","'s","done","with","the","object",".","Otherwise",",","the","program","is","likely","to","hang","on","exit",".","Alternatively",",","of","course",",","one","can","just","use","the","file","as","a","context","manager",",","as","shown","above","."]
code: def __init__(self, path):
      self.running = False
      self.finished = False
  
      # Set up the Gstreamer pipeline.
      self.pipeline = Gst.Pipeline()
  
      self.dec = Gst.ElementFactory.make("uridecodebin", None)
      self.conv = Gst.ElementFactory.make("audioconvert", None)
      self.sink = Gst.ElementFactory.make("appsink", None)
  
      if self.dec is None or self.conv is None or self.sink is None:
          # uridecodebin, audioconvert, or appsink is missing. We need
          # gst-plugins-base.
          raise IncompleteGStreamerError()
  
      # Register for bus signals.
      bus = self.pipeline.get_bus()
      bus.add_signal_watch()
      bus.connect("message::eos", self._message)
      bus.connect("message::error", self._message)
  
      # Configure the input.
      uri = "file://" + quote(os.path.abspath(path))
      self.dec.set_property("uri", uri)
      # The callback to connect the input.
      self.dec.connect("pad-added", self._pad_added)
      self.dec.connect("no-more-pads", self._no_more_pads)
      # And a callback if decoding fails.
      self.dec.connect("unknown-type", self._unkown_type)
  
      # Configure the output.
      # We want short integer data.
      self.sink.set_property(
          "caps",
          Gst.Caps.from_string("audio/x-raw, format=(string)S16LE"),
      )
      # TODO set endianness?
      # Set up the characteristics of the output. We don't want to
      # drop any data (nothing is real-time here); we should bound
      # the memory usage of the internal queue; and, most
      # importantly, setting "sync" to False disables the default
      # behavior in which you consume buffers in real time. This way,
      # we get data as soon as it's decoded.
      self.sink.set_property("drop", False)
      self.sink.set_property("max-buffers", BUFFER_SIZE)
      self.sink.set_property("sync", False)
      # The callback to receive decoded data.
      self.sink.set_property("emit-signals", True)
      self.sink.connect("new-sample", self._new_sample)
  
      # We'll need to know when the stream becomes ready and we get
      # its attributes. This semaphore will become available when the
      # caps are received. That way, when __init__() returns, the file
      # (and its attributes) will be ready for reading.
      self.ready_sem = threading.Semaphore(0)
      self.caps_handler = self.sink.get_static_pad("sink").connect(
          "notify::caps", self._notify_caps
      )
  
      # Link up everything but the decoder (which must be linked only
      # when it becomes ready).
      self.pipeline.add(self.dec)
      self.pipeline.add(self.conv)
      self.pipeline.add(self.sink)
  
      self.conv.link(self.sink)
  
      # Set up the queue for data and run the main thread.
      self.queue = queue.Queue(QUEUE_SIZE)
      self.thread = get_loop_thread()
  
      # This wil get filled with an exception if opening fails.
      self.read_exc = None
  
      # Return as soon as the stream is ready!
      self.running = True
      self.got_caps = False
      self.pipeline.set_state(Gst.State.PLAYING)
      self.ready_sem.acquire()
      if self.read_exc:
          # An error occurred before the stream became ready.
          self.close(True)
          raise self.read_exc
  
imports: import gi
  from gi.repository import GLib, Gst
  import sys
  import threading
  import os
  import queue
  from urllib.parse import quote
  from .exceptions import DecodeError
  from .base import AudioFile
label_desc: Use image node_id 1 to create a new GstAudioFile object from inherited base classes: AudioFile with example: obj = GstAudioFile(path)