Event Filters

Event Filters decide which detections are worth keeping. Use them to stop recording every passing cat, or to only ever be alerted about people.

Turning Them On

• Edit the Monitor, find the detector settings and set Event Filters to Yes. Save.
• Open Event Filters from the left side menu, then pick your Monitor from the dropdown at the top.
• Under Saved Filters, click Add New and give the filter a name.
• Under Conditions, click Add New to add a rule row.
• Set what you want to happen under Action for Selected, then Save.

Cannot find the Event Filters option? Switch Simple to Advanced in the bottom right corner of the Monitor Settings.

How A Filter Works

A filter is a list of conditions plus what to do about them. Each condition row reads like a sentence:

Object Tag   Contains   person

Rows are joined with AND or OR, set at the end of each row. Shinobi checks all the rows, then decides whether the filter matched.

The Drop Event setting is the important one. It has three choices:

• No — never drop the event. When the conditions match, apply the actions below instead.
• On Condition Succeed — drop the event when the conditions match. This is a blocklist: "if you see this, ignore it."
• On Condition Failure — drop the event when the conditions do not match. This is an allowlist: "only keep this."

Only Keep Certain Objects

This is the most common thing people want, and the easiest to get wrong. To only keep people, cars and trucks, build it like this:

Object Tag   Contains   person   OR
Object Tag   Contains   car      OR
Object Tag   Contains   truck

Drop Event:  On Condition Failure

Read it as: "if it is a person, a car or a truck, keep it — otherwise throw it away."

Do not build it the inverted way. Stacking Does Not Contain rows joined with AND and setting Drop Event to On Condition Succeed looks like it should do the same thing, but it does not. That combination removes objects one row at a time, so each row strips out the very objects the other rows were trying to keep. It appears to work with a single tag and quietly breaks as soon as you add a second.

Ignore Certain Objects

The reverse is simpler. To ignore cats entirely:

Object Tag   Contains   cat

Drop Event:  On Condition Succeed

What You Can Test

• Object Tag — what was detected, such as person or car.
• Confidence — how sure the detector was. Handy for dropping weak guesses.
• Object Count — how many things were found.
• X Point, Y Point, Width, Height — where the object was and how big it appeared.
• Region Name — which detection Region it happened in.
• Reason — what caused the event, such as motion or object.
• Detection Engine — which plugin reported it.
• Time — the time of day, written as HH:MM:SS.
• Indifference — the motion confidence value.

Comparisons are Equal to, Not Equal to, Contains and Does Not Contain, plus the usual greater/less than options for numbers.

Rows about objects — tag, confidence, size and position — are checked against every object in the event, not just the first one.

Doing Something Other Than Dropping

Leave Drop Event on No and the filter becomes a way to change what happens when its conditions match:

• Save Events — store the event in the database.
• Use Record Method — start a recording.
• Modify Indifference — require a different motion confidence for this case.
• Detector Command — run a command.
• Legacy Webhook — call a URL.

Any action left on Original Choice keeps whatever the Monitor is already set to do. So a filter like "Object Tag Contains person" with Use Record Method set will record only when a person shows up, while still leaving other detections alone.

Tips

• Start with one condition and test it before adding more. Long chains are hard to reason about.
• Use OR when listing several things you care about. Use AND when every part must be true at once.
• Brackets are available for grouping, but every ( needs a matching ). If they do not balance, Shinobi ignores all of them and logs a warning.
• A filter set to No under Enabled is skipped entirely, which is useful for testing without deleting your work.
• You can have several filters on one Monitor. They are all checked, so keep each one focused on a single job.
• Filter for Objects only in the Monitor's detector settings limits filtering to object detections, leaving plain motion events alone.