[.. upper level ..]

Audio functions

Functions for playing audio-files and setting volume.
There are predefined volume-groups into which audiostreams are put:
- a group for sound
- a group for music
- a group for speech
The volume of these groups can be set individually.

• Structures and Enumerations


• Creating and destroying audiostreams
• VG3_audio_load()
  
  Load a soundfile (wave-, flac-, mp3- or midi-file), creating an audiostream.
• VG3_audio_clone()
  
  Create a new audiostream from an existing one (copy).
• VG3_audio_unload()
  
  Destroy an audiostream, audiostreams of a volume-group or all audiostreams.


• Using audiostreams
• VG3_audio_play()
  
  Play an audiostream.
• VG3_audio_isplaying()
  
  Check if an audiostream is playing.
• VG3_audio_pause()
  
  Pause or continue playing an audiostream, audiostreams of a volume-group or all audiostreams.
• VG3_audio_suspend()
  
  Suspend or continue playing audio generally.
• VG3_audio_stop()
  
  Stop playing an audiostream, audiostreams of a volume-group or all audiostreams.


• Volume
• VG3_audio_volume()
  
  Set main volume or volume of a volume-group.
• VG3_audio_mute()
  
  Set audio playing to mute or unset it.


• Helper function for volume-groups
• VG3_audio_group()
  
  A parameter-function for VG3_audio_pause(), VG3_audio_stop() and VG3_audio_unload() to pass a volume-group instead of a single audiostream.

Example

  /* Play an audio file "music.wav" until it has been ended
   * and check for key-strokes for pausing, changing volume and (un)muting
   */

  struct vg3_window *wstruct;
  int winw, winh;

  /* open window */
  wstruct = VG3_window_new(argv[0], VGAG3_VGAVERSION_LOW, VGAG3_WINSCALE_BESTSCALE);
  if (wstruct == NULL) { fprintf(stderr, "%s\n", VG3_error()); exit(1); }

  /* get the size of the window */
  VG3_window_getsize(wstruct, &winw, &winh);

  /* play a sound "music.wav" until it is over */
  { struct vg3_image *imgptr;
    struct vg3_text stxt;
    int audkz;
    int obpause = 0;
    const char *infotext =
      "[P] = pause/continue\n[Q] = quit\n[1] = -volume\n[2] = +volume\n[M] = (un)mute\n\nPlaying once...";

    /* create text-info image */
    VGAG3_TEXT_ATTRIBUTES_SET(&stxt, NULL, '\n', 0, infotext);
    imgptr = VG3_image_text(wstruct, &stxt, VGAG3_COLOR_YELLOW, VGAG3_COLOR_TRANSPARENT);
    if (imgptr == NULL) { fprintf(stderr, "%s\n", VG3_error()); goto byebye; }

    /* load "music.wav" and play it once with crescendo */
    audkz = VG3_audio_load(wstruct, "music.wav", 100, VGAG3_AUDIO_VOLUME_SOUND);
    if (audkz == 0) { fprintf(stderr, "loading music.wav: %s\n", VG3_error()); goto byebye; }
    VG3_audio_play(wstruct, audkz, 0, 1);

    /* copy the text-info image centered to the window */
    VG3_image_copy(wstruct, NULL, imgptr, winw / 2, winh / 2, NULL, 0);

    /* update window contents and wait for end of sound or pressing key */
    VG3_discard_input(wstruct);
    for (;;) {
      if (VG3_inputevent_update(wstruct) > 0) { break; }

      /* pause or continue playing sound */
      if (VG3_key_ispressed(wstruct, VGAG3_KEY_P, VGAG3_IS_NEW_PRESSED)) {
        obpause = !obpause;
        VG3_audio_pause(wstruct, audkz, obpause);
      }

      /* quit */
      if (VG3_key_ispressed(wstruct, VGAG3_KEY_Q, VGAG3_IS_NEW_PRESSED)) { break; }

      /* decrease volume */
      if (VG3_key_ispressed(wstruct, VGAG3_KEY_1, VGAG3_IS_PRESSED)) {
        int val = VG3_audio_volume(wstruct, VGAG3_AUDIO_VOLUME_SOUND, -1);
        VG3_audio_volume(wstruct, VGAG3_AUDIO_VOLUME_SOUND, val - 10);
      }

      /* increase volume */
      if (VG3_key_ispressed(wstruct, VGAG3_KEY_2, VGAG3_IS_PRESSED)) {
        int val = VG3_audio_volume(wstruct, VGAG3_AUDIO_VOLUME_SOUND, -1);
        VG3_audio_volume(wstruct, VGAG3_AUDIO_VOLUME_SOUND, val + 10);
      }

      /* (un)mute playing sound */
      if (VG3_key_ispressed(wstruct, VGAG3_KEY_M, VGAG3_IS_NEW_PRESSED)) {
        int val = VG3_audio_mute(wstruct, -1);
        VG3_audio_mute(wstruct, !val);
      }

      /* quit, if playing sound is ended */
      if (!VG3_audio_isplaying(wstruct, audkz)) { break; }

      VG3_window_update(wstruct, 0, 0);

      VG3_wait_time(50);
    }
    VG3_discard_input(wstruct);

    /* (stop and) unload the sound */
    VG3_audio_unload(wstruct, audkz);

    /* free the image */
    VG3_image_unload(wstruct, imgptr);
  }

  /* if an error occurred after creating the window, close it before exiting */
  byebye:
  /* close window */
  VG3_window_free(wstruct);