Jellyfin.Plugin.Webdav/NextcloudPluginPlan.md

Nextcloud/WebDAV Jellyfin Plugin Plan

Below is a high-level plan for a Jellyfin plugin that integrates Nextcloud/WebDAV sources as library content.

flowchart TD
  subgraph Plugin Core
    A[PluginConfiguration<br/>– holds URL, creds, paths]
    B[Plugin<br/>– BasePlugin<Config>]
    C[IPluginServiceRegistrator<br/>– registers services]
    D[IHostedService<br/>– hook on startup]
  end

  subgraph Services
    E[WebDavClientService<br/>– wraps WebDav.Client]
    F[RemoteLibraryProvider<br/>– implements virtual folder scanning]
    G[CachingLayer<br/>– buffer / temporary file cache]
    H[StreamingController<br/>– ControllerBase for proxying streams]
  end

  subgraph Jellyfin Core
    I[ILibraryManager<br/>– library registration]
    J[Scan Engine<br/>– calls provider to enumerate items]
    K[HTTP Pipeline<br/>– routes to controllers]
  end

  A --> B
  B --> C
  C --> E
  C --> F
  E --> F
  F --> J
  F --> G
  G --> H
  H --> K
  D --> I
  I --> J

1. Skeleton & Setup

• Copy the jellyfin-plugin-template and rename to Jellyfin.Plugin.Nextcloud.
• Update project metadata: plugin ID, name, version in .csproj.
• Add NuGet reference to WebDav.Client.

2. Configuration & Dependency Injection

• Define PluginConfiguration with URL, credentials, root path, and cache settings.
• Implement Plugin : BasePlugin<PluginConfiguration> to override Name, Id, and inject DI.
• Create IPluginServiceRegistrator to register services:
  • WebDavClientService (singleton)
  • RemoteLibraryProvider (scanning)
  • StreamingController (ASP.NET Controller)
• Register virtual folder with ILibraryManager.RegisterVirtualFolder on startup.

3. Scanning Integration

• Research Jellyfin scan engine provider interfaces.
• Implement RemoteLibraryProvider to list directories/files via WebDavClientService.
• Map each remote item to a BaseItem (e.g., Video, Folder) with metadata.
• Track ETags or timestamps to support incremental scans.

4. Streaming & Caching

• Create StreamingController : ControllerBase with endpoint /WebDav/Stream/{itemId}.
• Map itemId to remote path and stream via WebDavClientService.GetStream.
• Implement CachingLayer to buffer chunks and write to temp files to prevent stalls.

5. Admin UI

• Define configPage.html as an embedded resource and implement IHasWebPages in Plugin.cs to return a PluginPageInfo for the settings page.
• Update build.yaml to include a pages section:

  pages:
    - name: WebDAV
      embeddedResourcePath: Jellyfin.Plugin.Webdav.Configuration.configPage.html
  

• Rebuild the plugin so that MSBuild generates a plugin.json manifest containing the pages definition.
• Deploy the plugin.json, DLL, and dependencies to Jellyfin’s plugins folder.
• Restart Jellyfin to verify the “WebDAV” settings page appears under Admin → Plugins.

6. Testing & Validation

• Unit-test WebDavClientService using a test Nextcloud instance or mock.
• Deploy plugin locally; verify library shows Nextcloud virtual folders.
• Test playback to ensure smooth streaming.

7. Documentation & Release

• Write README with installation, configuration, and troubleshooting guidance.
• Bump version, package plugin (.nupkg), and publish to GitHub Releases.

Milestones

• M1: Plugin skeleton & DI wiring
• M2: Scanning proof-of-concept
• M3: Streaming proxy & caching
• M4: Admin UI & settings page
• M5: Testing, documentation, release