Index: ffmpeg_wrapper.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/ffmpeg_wrapper/ffmpeg_wrapper.module,v
retrieving revision 1.1.2.15
diff -u -p -b -r1.1.2.15 ffmpeg_wrapper.module
--- ffmpeg_wrapper.module	3 Sep 2008 14:28:33 -0000	1.1.2.15
+++ ffmpeg_wrapper.module	15 Sep 2008 16:26:51 -0000
@@ -1,10 +1,12 @@
 <?php
 
-/* $Id: ffmpeg_wrapper.module,v 1.1.2.15 2008/09/03 14:28:33 arthuregg Exp $ */
-
-// This implements a wrapper for FFmpeg so that we don't have to reinvent the 
-// the wheel everytime we want to do soemthing with video, audio, or images
+// $Id: ffmpeg_wrapper.module,v 1.1.2.15 2008/09/03 14:28:33 arthuregg Exp $
 
+/**
+ * @file
+ * This implements a wrapper for FFmpeg so that we don't have to reinvent the 
+ * the wheel everytime we want to do soemthing with video, audio, or images
+ */
 
 /* ************************************************ */
 /* DRUPAL HOOKS */
@@ -12,8 +14,6 @@
 
 /**
  * Implementation of hook_menu().
- * @param boolean $may_cache
- * @return array of menu items
  */
 function ffmpeg_wrapper_menu($may_cache) {
   $items = array();
@@ -38,7 +38,7 @@ function ffmpeg_wrapper_menu($may_cache)
 
 
 /**
- * implementation of hook_perm()
+ * Implementation of hook_perm().
  */
 function ffmpeg_wrapper_perm() {
   return array('administer ffmpeg wrapper');
@@ -46,8 +46,7 @@ function ffmpeg_wrapper_perm() {
 
 
 /**
- * builds the admin form
- * @return drupal form array
+ * Build the admin form.
  */
 function ffmpeg_wrapper_admin() {
 
@@ -122,10 +121,7 @@ function ffmpeg_wrapper_admin() {
 
 
 /**
- * validate the options on the ffmpeg form
- *
- * @param int $form_id
- * @param array $form_values
+ * Validate the options on the ffmpeg form.
  */
 function ffmpeg_wrapper_admin_validate($form_id, $form_values) {
   // make sure we've got the path to the ffmpeg binary
@@ -145,11 +141,16 @@ function ffmpeg_wrapper_admin_validate($
 
 
 /**
- * gets data from ffmpeg
- * @param string $options are the options to run ffmpeg with
- * @param boolean $error_check runs error checking on the output
- * @param string $path overrides the system settings
- * @return output of the command
+ * Get data from ffmpeg.
+ * 
+ * @param $options
+ *   The options to run ffmpeg with.
+ * @param $error_check
+ *   If TRUE, runs error checking on the output.
+ * @param $path 
+ *   Overrides the system settings.
+ * @return
+ *   Output of the command.
  */
 function ffmpeg_wrapper_run_command($options, $error_check = true, $path) {
   if (! $path) {
@@ -170,7 +171,7 @@ function ffmpeg_wrapper_run_command($opt
  
   // do error handling if requested
   if ($error_check) {
-    if (! ffmpeg_wrapper_error_check($command_output, $command, true)){
+    if (! ffmpeg_wrapper_error_check($command_output, $command, true)) {
       return false;
     }
   }
@@ -179,10 +180,12 @@ function ffmpeg_wrapper_run_command($opt
 }
 
 /**
- * builds a list of the ffmpeg vhook options installed on this machine
+ * Build a list of the ffmpeg vhook options installed on this machine.
  *
- * @param string $path
- * @return array
+ * @param $path
+ *   Overrides the system settings.
+ * @return
+ *   Array of options.
  */
 function ffmpeg_wrapper_vhook_list($path) {
   static $files;
@@ -218,18 +221,22 @@ function ffmpeg_wrapper_vhook_list($path
 
 
 /**
- * checks an incoming file path extension to
- * see if it can be decoded 
- * @param $file is a full system filepath
- * @return true if file is in the list of decodeable files
+ * Check an incoming file path extension to see if it can be decoded.
+ * 
+ * @param $file
+ *   A full system filepath.
+ * @return
+ *   TRUE if file is in the list of decodeable files.
  */
-function ffmpeg_wrapper_can_decode($path){
+function ffmpeg_wrapper_can_decode($path) {
   $file_types = ffmpeg_wrapper_get_file_formats('decode');  
   $path_parts = pathinfo($path);
   
   // exception handling  
   // WMVs are sometimes asf files
-  if (preg_match('/wmv/i', $path_parts['extension'])) {$exception = 'asf';}
+  if (preg_match('/wmv/i', $path_parts['extension'])) {
+    $exception = 'asf';
+  }
   
   if ($file_types) { 
     foreach ($file_types as $file_type) {
@@ -245,12 +252,15 @@ function ffmpeg_wrapper_can_decode($path
 
 
 /**
- * gets an array of codec types usable on this system
- * this should probably be smoothed out so that it doesn't rely on
- * text so much
+ * Get an array of codec types usable on this system.
+ * This should probably be smoothed out so that it doesn't rely on text so
+ * much.
  * @ TODO this needs to be rethought to pass params right
- * @param string $ret determins hand back of encode/decode
- * @return is array of codecs or specific encode/decode options
+ * 
+ * @param $ret
+ *   Determins hand back of encode/decode.
+ * @return
+ *   Array of codecs or specific encode/decode options.
  */
 function ffmpeg_wrapper_get_codecs($ret = null) { 
   
@@ -325,9 +335,12 @@ function ffmpeg_wrapper_get_codecs($ret 
 
 
 /**
- * returns a list of codecs in key value form
- * @param string $type audio or video
- * @return array 
+ * Get a list of codecs in key value form.
+ * 
+ * @param $type
+ *   Audio or video.
+ * @return 
+ *   Array of codec names.
  */
 function ffmpeg_wrapper_return_codecs($type) {
   static $codecs;
@@ -350,10 +363,10 @@ function ffmpeg_wrapper_return_codecs($t
 
 
 /**
- * helper function to build the list of output formats 
- * on the system
+ * Helper function to build the list of output formats on the system.
  *
- * @return array of key values
+ * @return
+ *   Array of key values
  */
 function ffmpeg_wrapper_output_formats() {
 	static $formats;
@@ -362,7 +375,7 @@ function ffmpeg_wrapper_output_formats()
     $outputs = ffmpeg_wrapper_get_file_formats('encode');
     // rebuild as a select array
     $formats[0] = t('Please select');
-    foreach ($outputs as $output){
+    foreach ($outputs as $output) {
       $formats[$output] = $output;      
     }
 	}
@@ -370,19 +383,20 @@ function ffmpeg_wrapper_output_formats()
 }
 
 /**
- * builds the output rates for each type of bit rate that 
- * ffmpeg offers
+ * Build the output rates for each type of bit rate that ffmpeg offers.
  *
- * @param string $type
- * @return array of key values
+ * @param $type
+ *   Type of bit rate: "ab", "ar", "fps" or "br".
+ * @return
+ *   Array of key values.
  */
 function ffmpeg_wrapper_output_rates($type) {
 	static $rates;	
 	if (! $rates) {
-		$rates = array (		
+    $rates = array(
 	   'ab'  => array(8 => 8, 16 => 16, 32 => 32, 64 => t('64k (default)'), 128 => 128, 192 => 192, 256 => 256),
 	   'ar' => array('11025' => t('11khz'), '22050' => t('22khz'), '32000' => t('32khz'), '44100' => t('44.1khz (default)') ),
-     'fps' => array(10 =>10, 15 => 15, 20 => 20, 25 => t('25 (default)'), 29.97 => 29.97),
+      'fps' => array(10 => 10, 15 => 15, 20 => 20, 25 => t('25 (default)'), 29.97 => 29.97),
      'br' => array('50k' => t('50kps'), '100k' => t('100kps'), '150k' => t('150kps'), '200k' => t('200kps'), '250k' => t('250kps'), '300k' => t('300kps'), '500k' => t('500kps'), '750k' => t('750kps'), '1000k' => t('1000kps'), '1250k' => t('1250kps'), '1500k' => t('1500kps'), '2000k' => t('2000kps')),
  		);
 	}	
@@ -391,11 +405,14 @@ function ffmpeg_wrapper_output_rates($ty
 
 
 /**
- * gets an array of format types usable on this system
- * this should probably be smoothed out so that it doesn't rely on
- * text so much
- * @param string $ret determins what to hand back (encode/decode)
- * @return array of options
+ * Get an array of format types usable on this system.
+ * This should probably be smoothed out so that it doesn't rely on text so
+ * much.
+ * 
+ * @param $ret
+ *   Determins what to hand back (encode/decode).
+ * @return
+ *   Array of options.
  */
 function ffmpeg_wrapper_get_file_formats($ret = null) { 
   static $rows, $encode_formats, $decode_formats;
@@ -465,10 +482,14 @@ function ffmpeg_wrapper_get_file_formats
 
 
 /**
- * this gets the duration of a video
- * @param string $path is the path to file
- * @param boolean $timecode return time code or seconds
- * @return int is the duration in seconds or timecode as string
+ * Get the duration of a video.
+ * 
+ * @param $path
+ *   The path to file.
+ * @param $timecode
+ *   If TRUE, return time code, otherwise return seconds.
+ * @return
+ *   Duration in seconds as an integer or timecode as string.
  */
 function ffmpeg_wrapper_file_duration($path, $timecode) {
   // get duration from ffmpeg
@@ -501,10 +522,12 @@ function ffmpeg_wrapper_file_duration($p
 
 
 /**
- * checks to make sure that FFmpeg is in the path
- * @return boolean
+ * Check to make sure that FFmpeg is in the path.
+ * 
+ * @return
+ *   TRUE if FFmpeg can be executed, FALSE otherwise.
  */
-function ffmpeg_wrapper_executable(){
+function ffmpeg_wrapper_executable() {
   if (! ffmpeg_wrapper_run_command('')) {
     return false;     
   }
@@ -513,7 +536,10 @@ function ffmpeg_wrapper_executable(){
 
 
 /**
- * displays a table of the supported ffmpeg file formats
+ * Display a table of the supported ffmpeg file formats.
+ * 
+ * @return
+ *   The themed HTML form.
  */
 function ffmpeg_wrapper_formats_data_display() {
   $header = array(t('name'), t('type'), t('decode'), t('encode'), t('description') );
@@ -523,7 +549,10 @@ function ffmpeg_wrapper_formats_data_dis
 
 
 /**
- * displays a table of the ffmpeg encoding and decoding options
+ * Display a table of the ffmpeg encoding and decoding options.
+ * 
+ * @return
+ *   The themed HTML form.
  */
 function ffmpeg_wrapper_get_codecs_display() {
   $header = array(t('codec'), t('codec type'), t('decode'), t('encode'));
@@ -533,15 +562,16 @@ function ffmpeg_wrapper_get_codecs_displ
 
 
 /**
- * checks ffmpeg's output for errors and tries to handle them some way
- * @param string $output 
- *   is the output from a shell command
- * @param string $command
- *   the command run
- * @param boolean $watchdog
- *   log errors to drupal's watchdog
- * @return boolean 
- *   true if no errors, false if errors
+ * Check FFmpeg's output for errors and try to handle them some way.
+ * 
+ * @param $output
+ *   The output from a shell command.
+ * @param $command
+ *   The command run.
+ * @param $watchdog
+ *   If TRUE, log errors to Drupal's watchdog.
+ * @return
+ *   TRUE if no errors, FALSE if errors.
  * 
  **/
 function ffmpeg_wrapper_error_check($output, $command, $watchdog = true) {
@@ -572,17 +602,17 @@ function ffmpeg_wrapper_error_check($out
 
 
 /**
- * takes error conditions from the conversion process and deals
- * with them according to the admin configuration
+ * Take error conditions from the conversion process and deal
+ * with them according to the admin configuration.
  * 
- * @param string $output 
- *   is the command line output
- * @param string $error 
- *   is the problem being reported
- * @param boolean $watchdog 
- *   should we log this?
+ * @param $output
+ *   The command line output.
+ * @param $error
+ *   The problem being reported.
+ * @param $watchdog
+ *   If TRUE, log errors to Drupal's watchdog.
  */
-function ffmpeg_wrapper_error_log($command, $error, $watchdog){
+function ffmpeg_wrapper_error_log($command, $error, $watchdog) {
   // create an error log
   $message = t('FFmpeg failed to convert a file. FFmpeg said: @error Command was: ffmpeg @command', array('@error' => $error, '@command' => $command));  
   if ($watchdog) {
@@ -592,9 +622,12 @@ function ffmpeg_wrapper_error_log($comma
 
 
 /**
- * creates a path to the called vhook library
- * @param string $name
- * @return full path
+ * Create a path to the called vhook library.
+ * 
+ * @param $name
+ *   The name of the vhook library.
+ * @return
+ *   A full path.
  */
 function ffmpeg_wrapper_path_to_vhook($name) {
 	if ($path = file_exists(variable_get('ffmpeg_wrapper_vhook', '/usr/local/lib/vhook/') . $name)) {
@@ -607,30 +640,32 @@ function ffmpeg_wrapper_path_to_vhook($n
 /* ************************************************** */
 
 /**
- * takes an output format, returns an array of configuration
- * options. This is a hand built list. Will return default options
- * below to preserver form integrity while switching things
- * @param string $output
- *   this is an output type (eg: flv, avi, mp4, etc)
- * @return string
+ * Take an output format and return an array of configuration options.
+ * This is a hand built list. Will return default options below to preserve
+ * form integrity while switching things.
+ * 
+ * @param $output
+ *   An output type (eg: flv, avi, mp4, etc).
+ * @return
+ *   Array of configuration options.
  */ 
 function ffmpeg_wrapper_output_rules($output) {
-	// check to see if we have a configuration for this
+  // Check to see if we have a configuration for this.
 	$path = drupal_get_path('module', 'ffmpeg_wrapper');
 	if (file_exists($path .'/conf/'. $output .'.conf')) {
 		require_once($path .'/conf/'. $output .'.conf');
 		return $configuration;
 	}
 
-	// we don't have a configuration setting, load up the defaults
+  // We don't have a configuration setting, load up the defaults
 	// for any thing that we don't have data for. First check 
-	// and see if we have a cache
+  // and see if we have a cache.
 	//$cache = cache_get('ffmpeg_wrapper_default_output', 'cache');
 	if (unserialize($cache->data)) {
 	  return unserialize($cache->data);
 	}
 	
-	// no cache, build out the default options
+  // No cache, build out the default options.
 	$default['audio'] = array(
 	  'ab' => ffmpeg_wrapper_output_rates('ab'),
 	  'ar' => ffmpeg_wrapper_output_rates('ar'),
@@ -649,11 +684,10 @@ function ffmpeg_wrapper_output_rules($ou
 }
 
 /**
- * this displays the output rules as json 
+ * Display the output rules as json.
  * 
- * @param string $output
- *   this is an output type (eg: flv, avi, mp4, etc)
- * @return json
+ * @param $output
+ *   An output type (eg: flv, avi, mp4, etc).
  */
 function ffmpeg_wrapper_output_display($output) {
   // get the output rules for this 
@@ -666,11 +700,12 @@ function ffmpeg_wrapper_output_display($
 
 
 /**
- * load the js. This is a wrapper function just so other
- * modules can use this
- * @param string $prefix is the standard prefix to the elements that will be modified
- * @param string $bind_element is the name of the element (minus the prefix) that will be modifed
- * @return javascript to head of page
+ * Load the js. This is a wrapper function just so other modules can use this.
+ * 
+ * @param $prefix
+ *   The standard prefix to the elements that will be modified.
+ * @param $bind_element
+ *   The name of the element (minus the prefix) that will be modifed.
  */
 function ffmpeg_wrapper_enable($prefix, $bind_element = '') {
   // because of the way drupal handles form element ids, we have to transform
@@ -696,19 +731,18 @@ function ffmpeg_wrapper_enable($prefix, 
 /* ************************************************** */
 
 /**
- * This builds a generic form for any module to implement 
- * ffmpeg configuration. This will give any module the ajax 
- * form configuration updates. Validation and submission need
- * to be handled by the calling module- this only builds the form
- * call this form inside your form function
- * 
- * @param array $configuration 
- *   is configuration data- could be $form_values
- * @param string $prefix 
- *   is a prefix for the form elelements, needed for javascript activation on 
- *   complex forms (eg: media mover)
+ * Build a generic form for any module to implementm ffmpeg configuration.
+ * This will give any module the ajax form configuration updates. 
+ * Validation and submission need to be handled by the calling module - this 
+ * only builds the form call this form inside your form function.
+ *
+ * @param $configuration
+ *   An array of configuration data - could be $form_values.
+ * @param $prefix
+ *   A prefix for the form elelements, needed for javascript activation on
+ *   complex forms (eg: media mover).
  * @return array 
- *   drupal form array
+ *   A Drupal form array.
  */
 function ffmpeg_wrapper_configuration_form($configuration, $form_prefix = '' ) {