Motion Plugin - Config File Discussion

Motion 4.X will have a plugin interface. Plugins will handle input devices, make movies, etc etc.

With the new plugin interface the config file definition will have to be extended. So now is the time to redesign it completely.

The basic requirements that should be the starting point of any discussion or proposals.

• Plugins must read its config parameters from the motion.conf file. From Motion 4.0 the config file will contain parameters both for the global context and for each thread. No more thread files.
• Configuration files will be in a format which is easy to read and edit by humans without any additional tools.

Today we have no plugins. The new plugins will need config options. What we do not want are seperate config files for those. But how does a plugin know which options belong to itself? Well. The plugin can just read the config file and pick the options it knows and ignore the rest. So this is not an issue as such.

Another thing is that some options are common to many plugins and to the motion core. Examples are width and height.

There are several proposals that has come up on IRC and they all have their advantages and disadvantages.

One thing that causes a lot of trouble for newbies are the thread files. So it is more or less decided that the camera options that are unique goes into sections in the motion.conf.

XML has been proposed as a format but this kind of syntax is not newbie friendly. It is machine friendly.

In the following I will try some proposals and examples.

This topic is getting too long to it has been refactored the normal wiki way.

• MotionPluginConfigFileDiscussion Camera Threads
• MotionPluginConfigFileDiscussion Naming And Sections
• MotionPluginConfigFileDiscussion XML
• MotionPluginConfigFileDiscussion Plugin Option

Before we conclude anything.

Let us look at some advantages and disadvantages. It is when you combine the two new needs that it gets more complicated.

KennethLavrsen prefers the simple solutions. Use the Samba syntax and the prefix syntax. Kenneth (I) think that this is the most newbie friendly and also the one I would prefer myself. But I see clear advantages in the tags.

Samba label pros and cons

Advantages

• Very simple syntax. No end tag to forget

Disadvantages

• Nesting would be ugly. Noone would understand [/v4l]. That is ugly. I did not even suggest the Samba syntax for plugins because nesting using this syntax does not look good. Then we may as well use the XML tags.
• The only way to end a section is to define a new (or reach end of file). So camera 1 ends where camera 2 begins.

Plugin prefix pros and cons

Advantages

• You always know that a config parameter belongs to this one plugin.
• You always know which option people talk about on the mailing list and in bug reports and support requests.
• Plugins never have name clashes
• Simple one line per option syntax

Disadvantages

• Longer and maybe more ugly names. Badly named plugins could confuse newbie (but newbies would start with default distribution plugins and we can give them good names)

Tags pros and cons

Advantages

• Because the tags has both a start and end it should be possible for the parser to load them in any order and a little by little. We can mix them all up.
• Option names become shorter
• You can nest the tags used for threads and plugins.

Disadvantages.

• One single tag becomes 3 lines. You always need both the start and end tag.
• Nesting tags becomes ugly and hard to overview. I think the newbie will puke and maybe give up on the project just from looking at the default config file.
• Nesting can go two ways. You can nest cameras inside plugins. And plugins inside cameras. Are both allowed? If this is allowed people will be confused. If it is not allowed people will do it the wrong way.
• Remote control interface gets more complicated because the URL also will need the plugin name as part of the API.

Plugin option pros and cons

No summary yet

Using Samba label and prefix

See attached file: https://lavrsen.dk/foswiki/pub/Motion/MotionPluginConfigFileDiscussion/label_prefix.conf

Using Tags only

See attached file: https://lavrsen.dk/foswiki/pub/Motion/MotionPluginConfigFileDiscussion/tags_only.conf

Common option names

I have thought about having a small set of options that are used by any option of the same type.

height and width could be used by any option for example. But it may also make sense for an option to have its own. Example if an output type option is able to scale the graphics. But that is a major architectural change because of the text overlays being common to jpegs, mpegs and webcam stream. I propose not trying to save the world all at once and just implement the default plugins with same feature set as we have today.

So instead of v4l_height and ffmpeg_height etc the plugins just plain use a common option called height.

We could prefix all common options common_ but I actually do not see this as necessary.

Another example is the filename.

Instead of defining a ffmpeg_filename we could use movie_filename. The movie_filename is a common option that any movie_plugin uses.

movie_plugin ffmpeg

movie_plugin xvid

movie_plugin mpegencode

could be 3 different types of movie plugins that uses the option movie_filename.

This also makes it much more easy to control the features like on_xxxx that needs the filenames as parameter because the option name is generic and always the same.

I will try and modify the example above and actually make a complete motion.conf with the syntax and naming convension that I think is what we end up with. I have a good feeling about the whole thing now and I think we can come to the final conclusions Sunday (I am home alone again Sunday )

-- KennethLavrsen - 08 Oct 2005

Easy of implementing in code.

Whatever we choose it can be implemented. Parsing a text file to decode some options and their value is known territory. And it does not matter if it takes an extra hour to code. Or an extra day. This is the primary user interface for Motion and it is the user friendliness that counts here. So pros and cons related to the format have very little weight.

Conclusion

KennethLavrsen says that the tags only is going to be really ugly when more plugins are added and more tags are needed. I prefer the simple Samba label and prefix solution.

But there may be more ideas!!!! Come forward.

-- KennethLavrsen - 02 Oct 2005

• XML is out. Over my dead body.
• Format is plain text. Options are loaded with "option value". One option per line.
• The config file will have a global/common section with all the possible options including all the default plugins that ships with Motion. All have comments like we know them today.
  • Still need to conclude if the common/global section has a label in case of SAMBA syntax.
  • Still need to conclude what the name should be. None, global, common, ...?
  • Camera sections will not be called thread anymore. They will be called camera. "camera 1" camera 2" etc.
  • Camera sections are by default in the motion.conf file. If we make the include option people can have them in seperate files like today.
• Comments start with either # or ;
• Help comments have # and options that are default off are commented out with ;
• Options in camera sections will not have comments.
• Motion must still be able to save a config file.
  • Saving config files saves all options in the common/global section in a predictable way and options nicely grouped with group help text like today
  • Saving config files will preserve camera sections intact even if the value is the same as the common/global value (unlike today)
  • Include files??? Will they be merged into the motion.conf or remain as they are.
  • User added comments disappear when you load and save. I cannot see how we can clean up a config file when saving and preserve user comments.
  • Motion only saves config files when the user initiates it from http control.
  • Saving config adds options that were not in the original config file and with default values (diabled with ; if this is the default).
• Nesting sections looks too complicated - do not think it is needed. Code can do well without. Plugins do not need sections.
• Prefix syntax is the most user friendly way of having plugin unique options.
• Options are always lowercase and underscore is used for prefixing and separating words.
• Common core options can exist that will only be used in plugins.
• Plugins will have access to all options. Also options from the global scope. Plugins ADDS additional options. Prefix syntax is a naming convention only. The core and plugin code will not care about the prefixes.
• No conclusion on <camera 1> </camera1>> or [camera 1] syntax. Most likely is Samba section but I can still easily be convinced of the tag syntax.
• There is a wish for an include option that includes a config file and that is probably a good idea. This can also be used to activate and deactivate a camera with one simple character. But if we do we need to agree how motion saves the config files then and how Motion saves the included files.
• Still need to conclude on syntax to load plugins.

---

I prefer the label and prefix idea too. If we decide to go for this one, some options still have to be renamed to be more precise with their actual meaning.

If the thread config files are beeing integrated into the main motion.conf file, I would also like to have an easy option to 'deactivate' a camera (or input) without the need to comment out the whole section line by line.

-- JoergWeber - 07 Oct 2005

---