// Zaparoo Core // Copyright (c) 2026 The Zaparoo Project Contributors. // SPDX-License-Identifier: GPL-3.0-or-later // // This file is part of Zaparoo Core. // // Zaparoo Core is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // Zaparoo Core is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with Zaparoo Core. If not, see . package kodi import ( "bytes" "context" "encoding/base64" "encoding/json" "errors" "fmt" "io" "mime" "net/http" "strconv" "strings" "time" "github.com/ZaparooProject/zaparoo-core/v2/pkg/config" "github.com/ZaparooProject/zaparoo-core/v2/pkg/helpers/useragent" "github.com/ZaparooProject/zaparoo-core/v2/pkg/helpers/virtualpath" "github.com/ZaparooProject/zaparoo-core/v2/pkg/platforms" "github.com/ZaparooProject/zaparoo-core/v2/pkg/platforms/shared" "github.com/google/uuid" ) // Client implements the KodiClient interface type Client struct { watch *watchSettings url string noRepeat bool } // repeatMode is the Player.Open repeat option: "off" while completion is // tracked, empty (omitted) otherwise so requests are unchanged. func (c *Client) repeatMode() string { if c.noRepeat { return repeatOff } return "" } // Ensure Client implements KodiClient at compile time var _ KodiClient = (*Client)(nil) // NewClient creates a new Kodi client with configuration-based URL. // Uses "Kodi" as the default group for configuration lookup. func NewClient(cfg *config.Instance) KodiClient { return NewClientWithLauncherID(cfg, shared.LauncherGroupKodi, []string{shared.LauncherGroupKodi}) } // NewClientWithLauncherID creates a new Kodi client with group-aware configuration lookup. // Uses LookupLauncherDefaults to merge settings from matching groups and exact launcher ID. func NewClientWithLauncherID(cfg *config.Instance, launcherID string, groups []string) KodiClient { var serverURL string // Use LookupLauncherDefaults to get merged configuration from groups and launcher ID if cfg != nil { defaults := cfg.LookupLauncherDefaults(launcherID, groups) serverURL = defaults.ServerURL } // Fall back to hardcoded localhost if no config found if serverURL == "" { serverURL = "http://localhost:8080" } // Ensure URL has a scheme if serverURL != "" && !strings.HasPrefix(serverURL, "http://") && !strings.HasPrefix(serverURL, "https://") { serverURL = "http://" + serverURL } // Handle trailing slashes and ensure /jsonrpc endpoint serverURL = strings.TrimSuffix(serverURL, "/") if !strings.HasSuffix(serverURL, "/jsonrpc") { serverURL += "/jsonrpc" } return &Client{url: serverURL} } // LaunchFile launches a local file or URL in Kodi func (c *Client) LaunchFile(path string) error { _, err := c.APIRequest(context.Background(), APIMethodPlayerOpen, PlayerOpenParams{ Item: Item{ File: path, }, Options: ItemOptions{ Resume: true, Repeat: c.repeatMode(), }, }) return err } // LaunchMovie launches a movie by ID from Kodi's library func (c *Client) LaunchMovie(path string) error { idStr, err := virtualpath.ExtractSchemeID(path, shared.SchemeKodiMovie) if err != nil { return fmt.Errorf("failed to extract movie ID from path: %w", err) } movieID, err := strconv.Atoi(idStr) if err != nil { return fmt.Errorf("failed to parse movie ID %q: %w", idStr, err) } _, err = c.APIRequest(context.Background(), APIMethodPlayerOpen, PlayerOpenParams{ Item: Item{ MovieID: movieID, }, Options: ItemOptions{ Resume: true, Repeat: c.repeatMode(), }, }) return err } // LaunchTVEpisode launches a TV episode by ID from Kodi's library func (c *Client) LaunchTVEpisode(path string) error { idStr, err := virtualpath.ExtractSchemeID(path, shared.SchemeKodiEpisode) if err != nil { return fmt.Errorf("failed to extract episode ID from path: %w", err) } intID, err := strconv.Atoi(idStr) if err != nil { return fmt.Errorf("failed to parse episode ID %q: %w", idStr, err) } _, err = c.APIRequest(context.Background(), APIMethodPlayerOpen, PlayerOpenParams{ Item: Item{ EpisodeID: intID, }, Options: ItemOptions{ Resume: true, Repeat: c.repeatMode(), }, }) return err } // getFirstActivePlayer returns the first active player, or an error if none are active. func (c *Client) getFirstActivePlayer(ctx context.Context) (*Player, error) { players, err := c.GetActivePlayers(ctx) if err != nil { return nil, err } if len(players) == 0 { return nil, errors.New("no active players") } return &players[0], nil } // PlayPause toggles play/pause on the first active player func (c *Client) PlayPause(ctx context.Context) error { player, err := c.getFirstActivePlayer(ctx) if err != nil { return err } _, err = c.APIRequest(ctx, APIMethodPlayerPlayPause, PlayerPlayPauseParams{ PlayerID: player.ID, }) return err } // SetPaused pauses or resumes the first active player. Unlike PlayPause it is // idempotent: pausing a paused player or resuming a playing one changes nothing. func (c *Client) SetPaused(ctx context.Context, paused bool) error { player, err := c.getFirstActivePlayer(ctx) if err != nil { return err } _, err = c.APIRequest(ctx, APIMethodPlayerPlayPause, PlayerSetPlayingParams{ PlayerID: player.ID, Play: !paused, }) return err } // FastForward increases playback speed of the first active player func (c *Client) FastForward(ctx context.Context) error { player, err := c.getFirstActivePlayer(ctx) if err != nil { return err } _, err = c.APIRequest(ctx, APIMethodPlayerSetSpeed, PlayerSetSpeedParams{ PlayerID: player.ID, Speed: "increment", }) return err } // Rewind decreases playback speed of the first active player func (c *Client) Rewind(ctx context.Context) error { player, err := c.getFirstActivePlayer(ctx) if err != nil { return err } _, err = c.APIRequest(ctx, APIMethodPlayerSetSpeed, PlayerSetSpeedParams{ PlayerID: player.ID, Speed: "decrement", }) return err } // GoTo navigates to next or previous item in playlist. // Direction must be "next" or "previous". func (c *Client) GoTo(ctx context.Context, direction string) error { if direction != "next" && direction != "previous" { return fmt.Errorf("invalid GoTo direction: %q (must be \"next\" or \"previous\")", direction) } player, err := c.getFirstActivePlayer(ctx) if err != nil { return err } _, err = c.APIRequest(ctx, APIMethodPlayerGoTo, PlayerGoToParams{ PlayerID: player.ID, To: direction, }) return err } // Stop stops all active players in Kodi func (c *Client) Stop(ctx context.Context) error { players, err := c.GetActivePlayers(ctx) if err != nil { return err } for _, player := range players { _, err := c.APIRequest(ctx, APIMethodPlayerStop, PlayerStopParams{ PlayerID: player.ID, }) if err != nil { return err } } return nil } // Quit gracefully exits Kodi application func (c *Client) Quit(ctx context.Context) error { _, err := c.APIRequest(ctx, APIMethodApplicationQuit, nil) return err } // GetActivePlayers retrieves all active players in Kodi func (c *Client) GetActivePlayers(ctx context.Context) ([]Player, error) { result, err := c.APIRequest(ctx, APIMethodPlayerGetActivePlayers, nil) if err != nil { return nil, err } var players []Player err = json.Unmarshal(result, &players) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetActivePlayers response: %w", err) } return players, nil } // GetPlayerItem retrieves the currently playing item for a specific player func (c *Client) GetPlayerItem(ctx context.Context, playerID int) (*PlayerItem, error) { params := PlayerGetItemParams{ PlayerID: playerID, Properties: []string{ "title", "file", "artist", "album", "showtitle", "season", "episode", "year", }, } result, err := c.APIRequest(ctx, APIMethodPlayerGetItem, params) if err != nil { return nil, err } var response PlayerGetItemResponse err = json.Unmarshal(result, &response) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetPlayerItem response: %w", err) } return &response.Item, nil } // GetMovies retrieves all movies from Kodi's library func (c *Client) GetMovies(ctx context.Context) ([]Movie, error) { params := VideoLibraryGetMoviesParams{ Properties: []string{"title", "file"}, } result, err := c.APIRequest(ctx, APIMethodVideoLibraryGetMovies, params) if err != nil { return nil, err } var response VideoLibraryGetMoviesResponse err = json.Unmarshal(result, &response) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetMovies response: %w", err) } return response.Movies, nil } // GetTVShows retrieves all TV shows from Kodi's library func (c *Client) GetTVShows(ctx context.Context) ([]TVShow, error) { params := VideoLibraryGetTVShowsParams{ Properties: []string{"title", "uniqueid"}, } result, err := c.APIRequest(ctx, APIMethodVideoLibraryGetTVShows, params) if err != nil { return nil, err } var response VideoLibraryGetTVShowsResponse err = json.Unmarshal(result, &response) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetTVShows response: %w", err) } return response.TVShows, nil } // GetEpisodes retrieves all episodes for a specific TV show from Kodi's library func (c *Client) GetEpisodes(ctx context.Context, tvShowID int) ([]Episode, error) { params := VideoLibraryGetEpisodesParams{ TVShowID: tvShowID, Properties: []string{"title", "file", "tvshowid", "season", "episode"}, } result, err := c.APIRequest(ctx, APIMethodVideoLibraryGetEpisodes, params) if err != nil { return nil, err } var response VideoLibraryGetEpisodesResponse err = json.Unmarshal(result, &response) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetEpisodes response: %w", err) } return response.Episodes, nil } // GetSongs retrieves all songs from Kodi's library func (c *Client) GetSongs(ctx context.Context) ([]Song, error) { return c.fetchSongs(ctx, nil) } // GetAlbumSongs retrieves the songs of one album from Kodi's library func (c *Client) GetAlbumSongs(ctx context.Context, albumID int) ([]Song, error) { return c.fetchSongs(ctx, &SongFilter{AlbumID: albumID}) } // GetArtistSongs retrieves the songs of one artist from Kodi's library func (c *Client) GetArtistSongs(ctx context.Context, artistID int) ([]Song, error) { return c.fetchSongs(ctx, &SongFilter{ArtistID: artistID}) } func (c *Client) fetchSongs(ctx context.Context, filter *SongFilter) ([]Song, error) { params := AudioLibraryGetSongsParams{ Filter: filter, Properties: []string{"title", "displayartist", "album", "albumid", "duration", "file", "track", "disc"}, } result, err := c.APIRequest(ctx, APIMethodAudioLibraryGetSongs, params) if err != nil { return nil, err } var response AudioLibraryGetSongsResponse err = json.Unmarshal(result, &response) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetSongs response: %w", err) } return response.Songs, nil } // GetAlbums retrieves all albums from Kodi's library func (c *Client) GetAlbums(ctx context.Context) ([]Album, error) { params := AudioLibraryGetAlbumsParams{ Properties: []string{"title", "displayartist", "year"}, } result, err := c.APIRequest(ctx, APIMethodAudioLibraryGetAlbums, params) if err != nil { return nil, err } var response AudioLibraryGetAlbumsResponse err = json.Unmarshal(result, &response) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetAlbums response: %w", err) } return response.Albums, nil } // GetArtists retrieves all artists from Kodi's library func (c *Client) GetArtists(ctx context.Context) ([]Artist, error) { // No properties needed - we only use the default "label" field result, err := c.APIRequest(ctx, APIMethodAudioLibraryGetArtists, nil) if err != nil { return nil, err } var response AudioLibraryGetArtistsResponse err = json.Unmarshal(result, &response) if err != nil { return nil, fmt.Errorf("failed to unmarshal GetArtists response: %w", err) } return response.Artists, nil } // LaunchSong launches a song by ID from Kodi's library func (c *Client) LaunchSong(path string) error { idStr, err := virtualpath.ExtractSchemeID(path, shared.SchemeKodiSong) if err != nil { return fmt.Errorf("failed to extract song ID from path: %w", err) } songID, err := strconv.Atoi(idStr) if err != nil { return fmt.Errorf("failed to parse song ID %q: %w", idStr, err) } _, err = c.APIRequest(context.Background(), APIMethodPlayerOpen, PlayerOpenParams{ Item: Item{ SongID: songID, }, Options: ItemOptions{ Resume: true, Repeat: c.repeatMode(), }, }) return err } // LaunchAlbum launches an album by ID from Kodi's library func (c *Client) LaunchAlbum(path string) error { idStr, err := virtualpath.ExtractSchemeID(path, shared.SchemeKodiAlbum) if err != nil { return fmt.Errorf("failed to extract album ID from path: %w", err) } albumID, err := strconv.Atoi(idStr) if err != nil { return fmt.Errorf("failed to parse album ID %q: %w", idStr, err) } _, err = c.APIRequest(context.Background(), APIMethodPlayerOpen, PlayerOpenParams{ Item: Item{ AlbumID: albumID, }, Options: ItemOptions{ Resume: true, Repeat: c.repeatMode(), }, }) return err } // LaunchArtist launches an artist by ID from Kodi's library func (c *Client) LaunchArtist(path string) error { idStr, err := virtualpath.ExtractSchemeID(path, shared.SchemeKodiArtist) if err != nil { return fmt.Errorf("failed to extract artist ID from path: %w", err) } artistID, err := strconv.Atoi(idStr) if err != nil { return fmt.Errorf("failed to parse artist ID %q: %w", idStr, err) } _, err = c.APIRequest(context.Background(), APIMethodPlayerOpen, PlayerOpenParams{ Item: Item{ ArtistID: artistID, }, Options: ItemOptions{ Resume: true, Repeat: c.repeatMode(), }, }) return err } // resolveShow finds the show a kodi-show path names in Kodi's current library. func resolveShow(ctx context.Context, client KodiClient, path string) (TVShow, error) { reference, err := parseTVShowReference(path) if err != nil { return TVShow{}, err } shows, err := client.GetTVShows(ctx) if err != nil { return TVShow{}, fmt.Errorf("failed to resolve current Kodi TV show ID: %w", err) } showID, err := resolveTVShowID(reference, shows) if err != nil { return TVShow{}, err } for _, show := range shows { if show.ID == showID { return show, nil } } return TVShow{ID: showID, Label: reference.Name}, nil } // LaunchTVShow resolves a durable show identity and launches its episodes as a playlist. func (c *Client) LaunchTVShow(path string) error { show, err := resolveShow(context.Background(), c, path) if err != nil { return err } showID := show.ID // Step 1: Clear video playlist (playlistid=1) _, err = c.APIRequest(context.Background(), APIMethodPlaylistClear, PlaylistClearParams{ PlaylistID: 1, }) if err != nil { return err } // Step 2: Get episodes for the show episodes, err := c.GetEpisodes(context.Background(), showID) if err != nil { return err } if len(episodes) == 0 { return fmt.Errorf("no episodes found for show ID %d", showID) } // Step 3: Add episodes to playlist episodeItems := make([]PlaylistItemEpisodeID, 0, len(episodes)) for _, episode := range episodes { episodeItems = append(episodeItems, PlaylistItemEpisodeID{EpisodeID: episode.ID}) } _, err = c.APIRequest(context.Background(), APIMethodPlaylistAdd, PlaylistAddEpisodesParams{ PlaylistID: 1, Item: episodeItems, }) if err != nil { return err } // Step 4: Start playback _, err = c.APIRequest(context.Background(), APIMethodPlayerOpen, PlayerOpenParams{ Item: Item{ PlaylistID: 1, }, Options: ItemOptions{ Repeat: c.repeatMode(), }, }) return err } // GetURL returns the current Kodi API URL func (c *Client) GetURL() string { return c.url } // SetURL sets the Kodi API URL func (c *Client) SetURL(url string) { c.url = url } const maxAPIResponseBytes = 64 << 20 // APIRequest makes a raw JSON-RPC request to Kodi API func (c *Client) APIRequest(ctx context.Context, method APIMethod, params any) (json.RawMessage, error) { req := APIPayload{ JSONRPC: "2.0", ID: uuid.New().String(), Method: method, Params: params, } reqJSON, err := json.Marshal(req) if err != nil { return nil, fmt.Errorf("failed to marshal request: %w", err) } // Combine cancellation with timeout - whichever comes first wins reqCtx, cancel := context.WithTimeout(ctx, 30*time.Second) defer cancel() kodiReq, err := http.NewRequestWithContext(reqCtx, http.MethodPost, c.url, bytes.NewBuffer(reqJSON)) if err != nil { return nil, fmt.Errorf("failed to create request: %w", err) } kodiReq.Header.Set("Content-Type", "application/json") kodiReq.Header.Set("Accept", "application/json") if auth := authorizationHeader(c.url); auth != "" { kodiReq.Header.Set("Authorization", auth) } client := &http.Client{Transport: useragent.Transport(nil)} resp, err := client.Do(kodiReq) //nolint:gosec // G704: URL from user config, Kodi client's purpose if err != nil { return nil, fmt.Errorf("failed to send request: %w: %w", platforms.ErrScannerSourceUnreachable, err) } defer func() { _ = resp.Body.Close() // Ignore close error in defer }() if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices { return nil, fmt.Errorf("%w: unexpected HTTP status from kodi api: %d", platforms.ErrScannerSourceUnreachable, resp.StatusCode) } body, err := io.ReadAll(io.LimitReader(resp.Body, maxAPIResponseBytes+1)) if err != nil { return nil, fmt.Errorf("failed to read response body: %w", err) } if len(body) > maxAPIResponseBytes { return nil, fmt.Errorf("kodi api response exceeds %d bytes", maxAPIResponseBytes) } var apiResp APIResponse err = json.Unmarshal(body, &apiResp) if err != nil { mediaType, _, contentTypeErr := mime.ParseMediaType(resp.Header.Get("Content-Type")) if contentTypeErr != nil { mediaType = "invalid" } else if mediaType == "" { mediaType = "unspecified" } return nil, fmt.Errorf("%w: invalid kodi JSON response (status %d, content type %s)", platforms.ErrScannerSourceUnreachable, resp.StatusCode, mediaType) } if apiResp.Error != nil { return nil, fmt.Errorf("error from kodi api: %s", apiResp.Error.Message) } return apiResp.Result, nil } // authorizationHeader returns the configured Authorization header value for a // Kodi URL, or "" when no credentials are configured. func authorizationHeader(serverURL string) string { cred := config.LookupAuth(config.GetAuthCfg(), serverURL) if cred == nil { return "" } if cred.Bearer != "" { return "Bearer " + cred.Bearer } if cred.Username != "" && cred.Password != "" { return "Basic " + base64.StdEncoding.EncodeToString([]byte(cred.Username+":"+cred.Password)) } return "" }