Motion Plugin Config File Discussion - Naming And Sections

Refactored from MotionPluginConfigFileDiscussion

Plugins

So what about plugins. What if two plugins decide to need the same option but not the same value. Example speed, framerate, height, rotate, password etc. Maybe we want an output plugin to run with another rate than the input. Maybe we want the height and width smaller. Maybe we want to rotate the output movie independently of the input plugin. Maybe we need one password for a netcam and another for a MySQL database. Then we can not just call the option password without ensuring that each plugin know what belong to itself. Here are some proposals.

Proposal 1 - Prefix plugin unique options with the plugin name.

setup_mode off
input_plugin v4l
movie_plugin ffmpeg
v4l_videodevice /dev/video8 
v4l_input 8 
v4l_norm 0 
v4l_frequency 0 
v4l_auto_brightness off 
v4l_brightness 0 
v4l_contrast 0 
v4l_saturation 0 
v4l_hue 0 
rotate 0 
width 320 
height 240 
framerate 2 
switchfilter off 
threshold 1500 
threshold_tune off 
noise_level 32 
noise_tune on 
night_compensate off 
despeckle EedDl 
smart_mask_speed 8 
lightswitch 60 
minimum_motion_frames 1 
pre_capture 0 
post_capture 0 
gap 60 
minimum_gap 0 
max_mpeg_time 0 
low_cpu 0 
output_all off 
output_normal on 
output_motion off 
quality 75
ffmpeg_cap_new on 
ffmpeg_cap_motion off 
ffmpeg_timelapse 0 
ffmpeg_timelapse_mode daily 
ffmpeg_bps 500000 
ffmpeg_variable_bitrate 2 
ffmpeg_video_codec mpeg4 
snapshot_interval 0 

Proposal 2 - TAG syntax with begin and end tags

I have indented the options to enhance readability. That is what people would most likely do.

setup_mode off
input_plugin v4l
movie_plugin ffmpeg
<v4l>
    videodevice /dev/video8 
    input 8 
    norm 0 
    frequency 0 
    auto_brightness off 
    brightness 0 
    contrast 0 
    saturation 0 
    hue 0 
</v4l>
rotate 0 
width 320 
height 240 
framerate 2 
switchfilter off 
threshold 1500 
threshold_tune off 
noise_level 32 
noise_tune on 
night_compensate off 
despeckle EedDl 
smart_mask_speed 8 
lightswitch 60 
minimum_motion_frames 1 
pre_capture 0 
post_capture 0 
gap 60 
minimum_gap 0 
max_mpeg_time 0 
low_cpu 0 
output_all off 
output_normal on 
output_motion off 
quality 75
<ffmpeg>
    cap_new on 
    cap_motion off 
    timelapse 0 
    timelapse_mode daily 
    bps 500000 
    variable_bitrate 2 
    video_codec mpeg4
</ffmpeg> 
snapshot_interval 0

Proposal 3 - SECTIONS here too

This way everything looks the same and plugins can just ignore options outside their section.

Your proposal below seems hard to understand. Are you thinking of nesting the sections inside each other? Can you create a full motion.conf in this syntax with 3 cameras (like I did) so we can see how it will work in practical? -- KennethLavrsen - 03 Oct 2005

Update: Thanks for your clarification. To be it convinces me that the [label] syntax is not proper for nesting at all. I cannot see logically from the example below what is nested inside what. And what is a camera thread and what is not. More comments below -- KennethLavrsen - 03 Oct 2005

[plugin v4l]
    identifier v4l_1
    plugin_type input
    videodevice /dev/video8 
    input 8 
    norm 0 
    frequency 0 
    auto_brightness off 
    brightness 0 
    contrast 0 
    saturation 0 
    hue 0 
[motion]
    setup_mode off
    rotate 0 
    width 320 
    height 240 
    framerate 2 
    switchfilter off 
    threshold 1500 
    threshold_tune off 
    noise_level 32 
    noise_tune on 
    night_compensate off 
    despeckle EedDl 
    smart_mask_speed 8 
    lightswitch 60 
    minimum_motion_frames 1 
    pre_capture 0 
    post_capture 0 
    gap 60 
    minimum_gap 0 
    max_mpeg_time 0 
    low_cpu 0 
    output_all off 
    output_normal on 
    output_motion off 
    quality 75
    snapshot_interval 0
[plugin ffmpeg]
    identifier ffmpleg_1
    plugin_type video_encoder
    cap_new on 
    cap_motion off 
    timelapse 0 
    timelapse_mode daily 
    bps 500000 
    variable_bitrate 2 
    video_codec mpeg4
[plugin v4l]
    identifier v4l_2
    plugin_type input
    videodevice /dev/video7
    input 0
    norm 0 
    frequency 0 
    auto_brightness off 
    brightness 0 
    contrast 0 
    saturation 0 
    hue 0 
[plugin v4l]
    identifier v4l_2
    plugin_type input
    videodevice /dev/video0 
    input 8 
    norm 0 
    frequency 0 
    auto_brightness off 
    brightness 0 
    contrast 3
    saturation 2 
    hue 0 
[camera 1]
    ...
    input_plugin v4l_1
    output_plugin ffmpleg_1
    ...
[camera 2]
    ...
    input_plugin v4l_2
    output_plugin ffmpleg_1
    ...
[camera 3
    ...
    input_plugin v4l_3
    output_plugin ffmpleg_1
    ...

Note: this syntax is not nested. Every stanza is just a plain toplevel stanza.

All plugins of plugin_type input register themself as threads (cameras). Common options go inside the [motion] stanza. Plugins can override common options in their stanzas. plugin_type could be implicit (defined inside the plugin code) or like:

I think you have mixed up plugins and camera threads. No, I just assume every thread has an input plugin. So you could have as much threads as much input plugins you configure in motion.conf _ A camera thread belongs to one camera. A plugin is not a thread. Plugins are dynamic libraries that each camera thread can load. So camera thread 1 may load a v4l input plugin and an ffmpeg output plugin. And camera 2 can load the netcam plugin and the ffmpeg plugin. Each thread will use the global settings UNLESS the thread config redefines the value. -- KennethLavrsen - 03 Oct 2005_

[input v4l]
    videodevice /dev/video
    ...

Note: if you have to use a plugin twice with different options you have to put options twice in motion.conf. If you use prefix notation, this leads to f.e.

No. This is not true. Within each camera thread the same options can be reused. Just like we do today. _I think we are talking about the some thing but we are not understanding each other. The only difference is that what you call cameras I call input plugins. :-)_I just want to have the camera thread configs in the same motion.conf file instead of having one seperate file for each camera. I have suggested this because I think it is easier to manage and understand. I would never propose or accept a syntax like the one below (v4l_2_video...). The proposed prefix syntax is only to ensure that two plugins do not define conflicting option names. Each plugin will know which options it needs no matter what names and prefixes they have. And a plugin can/will use the generic Motion options as well like height and width. The prefix proposal also helps the user to know which options belongs to which plugin. -- KennethLavrsen - 03 Oct 2005

v4l_1_videodevice /dev/video0
v4l_2_videodevice /dev/video1

Proposal 4 - Nested sections

I'm looking at the problem "inside out". I start by considering what the code needs to know at execution time, and how it can find it in a "well defined" manner. Once I think I have that question answered, I then consider how we can make the requirement as "user friendly" as possible. The best I have been able to come up with so far is described below. I'm pretty sure it will (internally) result in a structure which can be used easily within the code and can be implemented relatively easily, but I'm not at all sure it's "friendly enough". I'd appreciate any comments and suggestions.

#
# Sections within the configuration file start with a "start tag" and
# end with an "end tag"
#
# A config param value can be one of several different types, including
# string, integer, boolean (true/false or yes/no) and section name.
#
# We start with our "outermost" global section
#
<global>
  #
  # Some simple global parameters
  #
  daemon         off
  setup_mode     on
  #
  # here we have two global parameters which we will later
  # over-ride within a video_input section
  #
  height         120
  width          160

  #
  # The next 4 parameters require an additional corresponding
  # section to be defined for each of them.  When the configuration
  # file is processed, a check *must* be made to assure each is
  # present.
  #
  video_input    camera1
  video_input    camera2
  video_input    camera3
  input_plugin   v4l

  #
  # Simple global nested section definition.  This one simply specifies
  # the global values which will be used unless "over-ridden" when
  # this section is later used, e.g. within a video_input section.
  # The fact that it has been previously declared as an "input_plugin"
  # would imply that we need to load the plugin "v4l_plugin", so the
  # "load_plugin" parameter is actually superfluous.  However, it
  # could be used to supply a non-standard path to find the code.
  # Note that the validation of the config file needs to assure that
  # the user doesn't try to load the same plugin from two different
  # places.
  #
  <v4l>
    load_plugin    v4l_plugin
    norm           pal
    #
    # Note that we "over-ride" the height and width.  This means that
    # anytime this section is used, these will be the "default" values
    #
    height         240
    width          320
  </v4l>

  #
  # These sections are a little more complicated, because they each
  # contain a "nested" section.  By specifying the nested section, the
  # camera can "over-ride" the global definitions (or supply them
  # if they are not supplied in the global one).  If the nested section
  # were not present, the global values would be used.
  #
  <camera1>
  input_plugin   v4l
    <v4l>
      video_device /dev/video3
      input        3
    </v4l>
  </camera1>

  #
  # This one "over-rides" the default height and width for the v4l device
  #
  <camera2>
  input_plugin   v4l
    <v4l>
      video_device /dev/video2
      input        1
      height       480
      width        320
    </v4l>
  </camera2>

  #
  # This third camera section also contains a nested section.  Here,
  # however, the nested section is necessary, because the plugin is
  # not globally defined and we need to specify at least the URL.
  #
  <camera2>
    input_plugin   netcam
    <netcam>
      load_plugin  netcam_plugin
      url          http://192.168.0.1
    </netcam>
  </camera2>

</global>

-- BillBrack - 07 Oct 2005

Thanks for the examples Bill. I had to read your proposal 3 times before I started understanding how it would work. And I do not think the config options inside nested sections will be easy for people to understand. Just look at the example with height and width inside the v4l tags. Will these also be valid for the ffmpeg plugin? My logic says no. I am getting more and more convinced that nesting sections is not at all needed. I do not see the code needs it. And always remember in all examples that we must have 1-10 lines of help text before each option which makes the nesting of options much more trouble and not as easy to overview as when you see a simple example with 3-5 options inside the tags.

The simpler proposal where you start with a global or common section followed by camera sections allows us to have a complete config file with all options in a logical sequence with help text for each option and extra help text before groups of options that belong together. Like for example we have today describing the most common convertion specifiers. And then below we have the camera sections containing only the unique options and without any help texts. We also have to consider that the config file must be writable by Motion. I find our current config file writing feature excellent. It is not perfect but almost. I would consider it a requirement that when you save the config file - all options - are saved in a predictable mannor and so that the config file becomes neat with all the help texts. This feature is so great for when you upgrade Motion and will also be very great when you install a new plugin. The camera sections will also be saved but without comments. One difference from today is that I do not want Motion to removed values from a camera section just because they have the same value as in the common section. This feature is not as smart as I thought it would be when we did it. With nested sections that can be made almost freely - it will be difficult to have a predictable save feature.

Your examples touches an important detail - the loading command for the plugins. I will start a new section below for that. -- KennethLavrsen - 07 Oct 2005

-- KennethLavrsen - 08 Oct 2005