search replacement plugin

[Chesyre 3]

Hi,

I'm currently developing a plugin that enhances Emby's native search functionality by replacing the default database queries with a Lucene.NET-powered search engine.

How it works:

Uses Harmony library to intercept search endpoints (/emby/ItemTypes, /emby/Users/{userId}/Items)
Indexes your entire media library using Lucene for full-text search
Returns results with configurable relevance scoring, fuzzy matching, and field boosts
Completely transparent to Emby clients - no client-side changes needed

The plugin is functional and working well in my testing. Before I invest more time in polishing it, I wanted to ask:

Is this type of plugin eligible for the official Emby Plugin Store? I know it uses runtime patching (Harmony), which might be a concern. The patches are non-destructive and only affect search endpoints when a SearchTerm is present - all other requests pass through to Emby normally.

Future plans:
I'm also considering adding a premium feature that would integrate Jellyseerr request functionality directly into Emby's search results. Users could request unavailable content right from the search interface without leaving Emby. This would be a paid add-on to help fund continued development.

Thanks in advance !

[softworkz 5065]

The GetItemTypes query has Emby SDK Reference: BaseItemsRequest as its basis, which has tons of query option properties. I can't imagine that you have implemented all this... Or do you just intercept under specific conditions?

 

14 minutes ago, Chesyre said:

Is this type of plugin eligible for the official Emby Plugin Store? I know it uses runtime patching (Harmony), which might be a concern.

You may be lucky because I know Harmony and I've used in a plugin before (but just temporarily to overome a server issue). I don't think its good as a regular solution. We should rather see whether we can provide a proper API surface for this purpose.

[Chesyre 3]

Yes, the plugin only intercepts under specific conditions:

1. Checks if request has a `SearchTerm` property
2. If `SearchTerm` is null/empty → passes through to Emby
3. If `SearchTerm` is present → routes to Lucene engine

Result: Library browsing, filters, sorting without search text = 100% native Emby behavior. Only text-based search queries use Lucene.

The plugin doesn't implement all BaseItemsRequest properties because it only handles the search path when SearchTerm exists. Everything else flows through Emby unchanged.

Regarding Harmony:
I understand the concerns. It would be interesting to have a native way to extend Emby's search without runtime patching. That said, the integration is fairly non-intrusive:
• Only 2 endpoints patched (GetItems/GetItemTypes)
• Conditional prefix checks before intercepting
• Non-search requests pass through unchanged
• Clean removal on disable

[softworkz 5065]

10 minutes ago, Chesyre said:

Yes, the plugin only intercepts under specific conditions:

1. Checks if request has a `SearchTerm` property
2. If `SearchTerm` is null/empty → passes through to Emby
3. If `SearchTerm` is present → routes to Lucene engine

Result: Library browsing, filters, sorting without search text = 100% native Emby behavior. Only text-based search queries use Lucene.

The plugin doesn't implement all BaseItemsRequest properties because it only handles the search path when SearchTerm exists. Everything else flows through Emby unchanged.

Well, I have some sympathy for this, because that's pretty much the same way like I would have done it.

 

11 minutes ago, Chesyre said:

Regarding Harmony:
I understand the concerns. It would be interesting to have a native way to extend Emby's search without runtime patching. That said, the integration is fairly non-intrusive:
• Only 2 endpoints patched (GetItems/GetItemTypes)
• Conditional prefix checks before intercepting
• Non-search requests pass through unchanged
• Clean removal on disable

These concerns are different from that, and thinking about it, it becomes quite a list:

• A major concern is platforms! When you look at the number of different packages we provide for each server release, you'll see what I mean
  Not all of them are .net 8, we still build a netframework version, a mono version, a ne6 version and there's also Android - all of them may are may not be challenging for Harmony. Last time I used it, it worked surprisingly reliable, but it's been a while. 
  In order to get into the catalog, a plugin must work everywhere
• We have some upcoming integrity validation checking against offline modifications and some runtime validation may follow later - possibly also some obfuscation methods which mightt stop Harmony from working, so it's not future-proof path
• We should not create a precedence case for allowing this. I think you know pretty well what I mean, that's why you emphasized "only 2 endpoints patched". When everybody starts doing this, we would no longer be really on charge of our software. It would be a support nightmare, becasue we would no longer know whether our own code is responsible for certain issues or whether a plugin has injected its own code. Not even the users will know it - only the plugin authors themselves.
• it is like drilling holes into our software without caring what happens later: that's another big issue: when our implementation changes, the patched code might no longer match, without being easily noticeable (like when public interfaces change), so users may see crazy issues and we would have no idea why it happens

All-in-all, I'd say this is okay as a proof-of-concept, for presentation and doing some tests and checking user feedback/reeception, but eventually this cannot continue with Harmony. Even when it would remain a non-catalog plugin, you need to be aware that it could stop working from one day to another - e.g. when we would see any illegal activity (like cracks) making use of it.

The right way forward is having an official extension point for this..

@Luke - what do you think about it?

 

[Luke 42077]

Quote

Is this type of plugin eligible for the official Emby Plugin Store?

I think we'll have to think about it and talk it over.  Ideally, intercepting a core route should not be possible. I would rather close that off and have you intercept search through some official means.

But also what softworkz mentioned about platforms is equally important. Either it has to work on all platforms or we have to build infrastructure for the catalog to list platform-specific entries.

[Chesyre 3]

I completely understand your point of view, and you’re absolutely right — I hadn’t considered all of those aspects.

I’ll continue developing the plugin and may distribute it outside the official store, clearly mentioning any platform limitations if there are any.
That should help determine whether there’s genuine user interest.

Once development is complete, I’ll have a clear list of all the endpoints required for it to work properly.
That could then serve as a basis to propose new official API routes for a long-term integration directly within Emby.

Thank you very much for your detailed responses and insights.
I’m planning to create a dedicated forum post to present and discuss the plugin once it’s functional — of course, only if you’re okay with that.

[softworkz 5065]

25 minutes ago, Chesyre said:

Once development is complete, I’ll have a clear list of all the endpoints required for it to work properly.
That could then serve as a basis to propose new official API routes for a long-term integration directly within Emby.

It wouldn't mean to add new API endpoints, because this would require changes to all clients - which would really make it a long-term operation.
The interception would rather happen behind the existing endpoint implementations - doing pretty much the same like you are doing yourself now.

We could expose an interface like 

public interface IFullTextSearchProvider
{
    QueryResult<BaseItem> GetQueryResult(BaseItemsRequest request, DtoOptions dtoOptions, out bool handled,...);
}

It might work even with just a single method, because both endpoints you mentioned are using BaseItemsRequest.

With a 'handled' parameter, the search provider could indicate whether the results should be taken or whether Emby Server should handle the request instead.
Of course you wouldn't get all requests like now - we'd limit it to those with FT search, but with a handled parameter,  you can always make sure to keep things on the safe side when there are queries that you cannot handle.

Please let me know what you think about it and whether anything else would be needed. Also it would be great when you could detail the conditions under which you are taking the queary or not.  

[Chesyre 3]

The IFullTextSearchProvider interface approach sounds perfect and would solve all the concerns you mentioned.

I intercept the request through Lucene only when ALL these conditions are met:

1. SearchTerm != null && SearchTerm.Length >= 2
2. ParentId is not present in the request (global search only, not folder-scoped browsing)
3. IncludeItemTypes contains supported types: Movie, Series, Episode, Person, Studio, BoxSet ...

If any condition fails → I return immediately and let Emby handle it (fallback to database).

The IFullTextSearchProvider interface with the handled parameter is exactly what I need. A few questions:

1. User context: Will the method receive a User object or just userId? I need it for UserData enrichment:
var userData = _userDataManager.GetUserData(user, item);

2. Return type: You mentioned QueryResult<BaseItem>, but I currently handle the full DTO conversion myself directly from the Lucene index (without any database queries) to achieve faster response times.

Should I:
Return BaseItem[] and let Emby handle DTO conversion (which would require database access)?
Continue handling conversion myself and return BaseItemDto[] (would require changing the interface signature)?
 

Edited October 30, 2025 by Chesyre

[softworkz 5065]

I've put that itnterface together without much thought about details, it was merely meant to illustrate the concept, don't take it by the letter.

 

25 minutes ago, Chesyre said:

1. User context: Will the method receive a User object or just userId? I need it for UserData enrichment:
var userData = _userDataManager.GetUserData(user, item);

The method can surely pass a user object, because it's available at the calling side anyway - no need to let you make your plugin do another query for it.

 

25 minutes ago, Chesyre said:

2. Return type: You mentioned QueryResult<BaseItem>, but I currently handle the full DTO conversion myself directly from the Lucene index (without any database queries) to achieve faster response times.

Should I:
Return BaseItem[] and let Emby handle DTO conversion (which would require database access)?
Continue handling conversion myself and return BaseItemDto[] (would require changing the interface signature)?

I let this for  @Luketo  answer, he knows these things better than me and it's his call anyway  

 

Edited October 30, 2025 by softworkz

[Luke 42077]

Quote

Return BaseItem[] and let Emby handle DTO conversion (which would require database access)?

Yes, this is what you should do, especially if you would like this to be in the catalog.

[Luke 42077]

What version of the server are you testing on?

[Chesyre 3]

Quote

What version of the server are you testing on?

I'm using the latest stable version: 4.9.1.80

[mammt 5]

On 31/10/2025 at 11:00, Chesyre said:

I'm using the latest stable version: 4.9.1.80

hello brother, did you stop working on it? current emby search is dogshit and they don't wanna fix it only a plugin is needed to fix it

[Chesyre 3]

On 1/26/2026 at 7:28 AM, mammt said:

hello brother, did you stop working on it? current emby search is dogshit and they don't wanna fix it only a plugin is needed to fix it

Hi!
No, development hasn't stopped.
I'm just balancing a few other projects at the moment. I’ve run into some challenges with the search engine while trying to make it truly efficient, but I'm still working on it. I hope to be able to release it soon!