OGMRip

Since version 0.11, OGMRip provides a plugin system for containers, video, audio, and subtitle codecs. This document is a case study of the implementation of a new audio codec to create AAC files using neroAacEnc.

Introduction

An OGMRip plugin is mainly made up of a GObject, a description of the capabilities of the plugin and a function to retrieve this description. Depending on the plugin you're writing, the GObject must implemente a specific type: an OGMRipContainer for a container, an OGMRipVideoCodec for a video codec, an OGMRipAudioCodec for an audio codec, and an OGMRipSubpCodec for a subtitles codec. The description is represented by a structure and is also related to the type of plugin: an OGMRipContainerPlugin for a container, an OGMRipVideoPlugin for a video codec, an OGMRipAudioPlugin for an audio codec, and an OGMRipSubpPlugin for a subtitles codec.

OGMRipNeroAac

First, we will define the OGMRipNeroAac object. As it is an audio codec, it must inherit from OGMRipAudioCodec:

typedef struct _OGMRipNeroAac      OGMRipNeroAac;
typedef struct _OGMRipNeroAacClass OGMRipNeroAacClass;

struct _OGMRipNeroAac
{
  OGMRipAudioCodec parent_instance;
};

struct _OGMRipNeroAacClass
{
  OGMRipAudioCodecClass parent_class;
};

G_DEFINE_TYPE (OGMRipNeroAac, ogmrip_nero_aac, OGMRIP_TYPE_AUDIO_Codec)

Specifying an object this way requires the definition of two functions before G_DEFINE_TYPE, one to initialize the class, and an other to initialize the object itself:

static void
ogmrip_nero_aac_class_init (OGMRipNeroAacClass *klass)
{
}

static void
ogmrip_nero_aac_init (OGMRipNeroAac *nouveau)
{
}

As is, the plugin can almost be compiled; only the headers are missing:

#include <ogmrip.h>
#include <ogmjob.h>

We can now compile it:

$ gcc -Wall -c ogmrip-nero-aac.c `pkg-config --cflags ogmrip`

And link it:

$ gcc -shared ogmrip-nero-aac.o -o libogmrip-nero-aac.so

Of course, the plugin does absolutely nothing at the moment. All the code concerning the encoding must still be written. neroAacEnc only supports inputs in the WAV format. We must then extract the audio track in WAV first, then encode it in AAC. Fortunately, these two steps can be done simultaneously through a named pipe (FIFO) and using an OGMJobPipeline.

Let's write the code to create the FIFO and add the pipeline:

static gint ogmrip_nero_aac_run (OGMJobSpawn *spawn);

static void
ogmrip_nero_aac_class_init (OGMRipAacClass *klass)
{
  OGMJobSpawnClass *spawn_class = OGMJOB_SPAWN_CLASS (klass);

  /*
   * Override the run() function
   */
  spawn_class->run = ogmrip_nero_aac_run;
}

static void
ogmrip_nero_aac_init (OGMRipNeroAac *nouveau)
{
}

G_DEFINE_TYPE (OGMRipNeroAac, ogmrip_nero_aac, OGMRIP_TYPE_AUDIO_CODEC)

static gint
ogmrip_nero_aac_run (OGMJobSpawn *spawn)
{
  OGMJobSpawn *pipeline;
  gchar *fifo;
  gint result;

  /*
   * Create the FIFO
   */
  fifo = ogmrip_fs_mkftemp ("fifo.XXXXXX", NULL);

  /*
   * Create the pipeline
   */
  pipeline = ogmjob_pipeline_new ();

  /*
   * Add the pipeline in the container
   */
  ogmjob_container_add (OGMJOB_CONTAINER (spawn), pipeline);

  /*
   * Unreference the pipeline
   */
  g_object_unref (pipeline);

  /*
   * Call the run() function of the parent object. This is a
   * blocking execution.
   */
  result = OGMJOB_SPAWN_CLASS (ogmrip_nero_aac_parent_class)->run (spawn);

  /*
   * After the encoding, remove the pipeline from the container
   */
  ogmjob_container_remove (OGMJOB_CONTAINER (spawn), pipeline);

  /*
   * Remove the FIFO
   */
  ogmrip_fs_unref (fifo, TRUE);

  return result;
}

There again, the plugin does almost nothing, but we've set up the foundation for the encoding by itself. Let's then write two functions to build the command lines for the extraction in WAV and the conversion in AAC.

static gchar **
ogmrip_wav_command (OGMRipAudioCodec *audio, const gchar *output)
{
  GPtrArray *argv;

  /*
   * A function to create the WAV/PCM command lines is available
   * in libogmrip-mplayer
   */
  argv = ogmrip_mplayer_wav_command (audio, TRUE, NULL, output);

  return (gchar **) g_ptr_array_free (argv, FALSE);
}

static gchar **
ogmrip_aac_command (OGMRipAudioCodec *audio, const gchar *input)
{
  GPtrArray *argv;
  const gchar *output;
  gint quality;

  /*
   * In OGMRip, the quality is ranged from 0 to 10
   */
  quality = ogmrip_audio_get_quality (audio);

  argv = g_ptr_array_new ();

  /*
   * The name of the executable
   */
  g_ptr_array_add (argv, g_strdup ("neroAacEnc"));

  /*
   * The quality in neroAacEnc is a floating-point number in 0..1 range
   */
  g_ptr_array_add (argv, g_strdup ("-q"));
  g_ptr_array_add (argv,
      g_strdup_printf ("%d.%d", quality / 10, quality % 10));

  /*
   * The input file; the FIFO, actually
   */
  g_ptr_array_add (argv, g_strdup ("-if"));
  g_ptr_array_add (argv, g_strdup (input));

  /*
   * The output file
   */
  g_ptr_array_add (argv, g_strdup ("-of"));
  output = ogmrip_codec_get_output (OGMRIP_CODEC (audio));
  g_ptr_array_add (argv, g_strdup (output));

  g_ptr_array_add (argv, NULL);

  return (gchar **) g_ptr_array_free (argv, FALSE);
}

Because we are using functions from libogmrip-mplayer, we've got to include the appropriate header file:

#include <ogmrip-mplayer.h>

Let's now modify the run() function to create the processes that will actually run the command lines we've just defined and add them in the pipeline.

static gint
ogmrip_nero_aac_run (OGMJobSpawn *spawn)
{
  OGMJobSpawn *pipeline;
  OGMJobSpawn *child;

  gchar *fifo, **argv;
  gint result = OGMJOB_RESULT_ERROR;

  /*
   * Create the FIFO
   */
  fifo = ogmrip_fs_mkftemp ("fifo.XXXXXX", NULL);

  /*
   * Create the pipeline
   */
  pipeline = ogmjob_pipeline_new ();

  /*
   * Add the pipeline in the container
   */
  ogmjob_container_add (OGMJOB_CONTAINER (spawn), pipeline);

  /*
   * Unreference the pipeline
   */
  g_object_unref (pipeline);

  /*
   * Create the command line for the WAV extraction
   */
  argv = ogmrip_wav_command (OGMRIP_AUDIO_CODEC (spawn), fifo);
  if (argv)
  {
    /*
     * Create the process
     */
    child = ogmjob_exec_newv (argv);

    /*
     * Add a function to parse the output of the process and report the
     * progression. This function is defined in libogmrip-mplayer
     */
    ogmjob_exec_add_watch_full (OGMJOB_EXEC (child),
        (OGMJobWatch) ogmrip_mplayer_wav_watch, spawn, TRUE, FALSE, FALSE);

    /*
     * Add the process in the container
     */
    ogmjob_container_add (OGMJOB_CONTAINER (pipeline), child);

    /*
     * Unreference the process
     */
    g_object_unref (child);

    /*
     * Create the command line for the conversion to AAC
     */
    argv = ogmrip_aac_command (OGMRIP_AUDIO_CODEC (spawn), fifo);
    if (argv)
    {
      /*
       * Create the process
       */
      child = ogmjob_exec_newv (argv);

      /*
       * Add the process in the container
       */
      ogmjob_container_add (OGMJOB_CONTAINER (pipeline), child);

      /*
       * Unreference the process
       */
      g_object_unref (child);

      /*
       * Call the run() function of the parent object. This is a
       * blocking execution.
       */
      result =
        OGMJOB_SPAWN_CLASS (ogmrip_nero_aac_parent_class)->run (spawn);
    }
  }

  /*
   * After then encoding, remove the pipeline from the container
   */
  ogmjob_container_remove (OGMJOB_CONTAINER (spawn), pipeline);

  /*
   * Remove the FIFO
   */
  ogmrip_fs_unref (fifo, TRUE);

  return result;
}

Description

Now that the object is completely written, we must fill the structure describing the capabilities of the plugin and the function to retrieve it.

This structure requires:

• a reference to the module; it must be initialized to NULL;
• a type which is the result of the ogmrip_nero_aac_get_type function;
• the name of the module;
• a description of the module;
• the output format of the module. OGMRip supports as many formats as MPlayer, they are all defined in the OGMRipFormatType enumerated type.

The function must be called ogmrip_init_plugin and returns a pointer to the structure. We also use this function to check the requirements, in this case, if mplayer is available and if neroAacEnc is in the PATH.

static OGMRipAudioPlugin nero_aac_plugin =
{
  NULL,
  G_TYPE_NONE,
  "nero-aac",
  "Nero AAC",
  OGMRIP_FORMAT_AAC
};

OGMRipPluginAudioCodec *
ogmrip_init_plugin (void)
{
  gchar *fullname;

  /*
   * Check for mplayer
   */
  if (!ogmrip_check_mplayer ())
    return NULL;

  /*
   * Check for neroAacEnc
   */
  fullname = g_find_program_in_path ("neroAacEnc");
  if (!fullname)
    return NULL;
  g_free (fullname);

  nero_aac_plugin.type = ogmrip_nero_aac_get_type ();

  return &nero_aac_plugin;
}

The only thing to do, now, is to copy the plugin in the directory in which OGMRip expects audio plugins. It should be either /usr/lib/ogmrip/audio-codecs, /usr/local/lib/ogmrip/audio-codecs, or $HOME/lib/ogmrip/audio-codecs. The plugins for video codecs, subtitle codecs, and containers must be installed in the video-codecs, subp-codecs, and containers directories, respectively.

And if everything went as expected, the plugin should automagically appears in the appropriate section of the Preferences dialog of OGMRip or in one of the lists of codecs and containers of shRip.

Conclusion

We've just seen how to create a new plugin for OGMRip to transcode audio tracks in AAC using neroAAC. Creating video ou subtitle plugins is almost similar besides some specificities in the description structure.

For instance, a video plugin should provide the maximum number of passes and threads it supports and a subtitle plugin should specify if it outputs text subtitles or not.

The description structure of a container is a bit more complex. It must specify if it supports B-frames, the maximum number of audio and subtitles streams it can contain and a list of all the formats it supports. For more information on this, you can check the code of the Matroska container plugin.

Of course, the source code of the NeroAAC plugin is available, you can use it as a template for further developments.