[#81] Playlist support

Author: jesperpedersen

doc/CLI.md

@@ -13,6 +13,7 @@ Options:
   -c, --config CONFIG_FILE   Set the path to the hrmp.conf file
                              Default: $HOME/.hrmp/hrmp.conf
   -D, --device               Set the device name
+  -p, --playlist PLAYLIST    Load files/directories from a playlist file (.hrmp)
   -R, --recursive            Add files recursive of the directory
   -I, --sample-configuration Generate a sample configuration
   -m, --metadata             Display metadata of the files
@@ -43,6 +44,21 @@ Select a non-default device for output
 hrmp -D "MyDAC" .
 ```
 
+## -p
+
+Load files from a playlist file. The playlist is a plain text file (typically ending in `.hrmp`) with one entry per line:
+
+* Relative file/directory path (relative to the playlist file directory)
+* Absolute file/directory path
+* `*` = all files in the playlist file directory
+* `**/*` = recursively add all files in the playlist file directory
+
+If both a playlist and files are provided on the command line, the playlist entries are queued first.
+
+```sh
+hrmp -p everlast.hrmp
+```
+
 ## -R
 
 Play supported music files, and recurse through directories

doc/GETTING_STARTED.md

@@ -14,6 +14,7 @@ Options:
   -c, --config CONFIG_FILE   Set the path to the hrmp.conf file
                              Default: $HOME/.hrmp/hrmp.conf
   -D, --device               Set the device name
+  -p, --playlist PLAYLIST    Load files/directories from a playlist file (.hrmp)
   -R, --recursive            Add files recursive of the directory
   -I, --sample-configuration Generate a sample configuration
   -m, --metadata             Display metadata of the files

doc/man/hrmp.1.rst

@@ -27,6 +27,9 @@ OPTIONS
 -D, --device
   Set the device name
 
+-p, --playlist PLAYLIST
+  Load files/directories from a playlist file (.hrmp)
+
 -R, --recursive
   Add files recursive of the directory
 

doc/manual/04-getting_started.md

@@ -16,6 +16,7 @@ Options:
   -c, --config CONFIG_FILE   Set the path to the hrmp.conf file
                              Default: $HOME/.hrmp/hrmp.conf
   -D, --device               Set the device name
+  -p, --playlist PLAYLIST    Load files/directories from a playlist file (.hrmp)
   -R, --recursive            Add files recursive of the directory
   -I, --sample-configuration Generate a sample configuration
   -m, --metadata             Display metadata of the files

doc/manual/05-cli.md

@@ -15,6 +15,7 @@ Options:
   -c, --config CONFIG_FILE   Set the path to the hrmp.conf file
                              Default: $HOME/.hrmp/hrmp.conf
   -D, --device               Set the device name
+  -p, --playlist PLAYLIST    Load files/directories from a playlist file (.hrmp)
   -R, --recursive            Add files recursive of the directory
   -I, --sample-configuration Generate a sample configuration
   -m, --metadata             Display metadata of the files
@@ -45,6 +46,21 @@ Select a non-default device for output
 hrmp -D "MyDAC" .
 ```
 
+## -p
+
+Load files from a playlist file. The playlist is a plain text file (typically ending in `.hrmp`) with one entry per line:
+
+* Relative file/directory path (relative to the playlist file directory)
+* Absolute file/directory path
+* `*` = all files in the playlist file directory
+* `**/*` = recursively add all files in the playlist file directory
+
+If both a playlist and files are provided on the command line, the playlist entries are queued first.
+
+```sh
+hrmp -p everlast.hrmp
+```
+
 ## -R
 
 Play supported music files, and recurse through directories

doc/manual/06-ui.md

@@ -59,6 +59,18 @@ The toolbar is laid out from left to right as follows:
      - **Shuffle**: randomize the order of playlist entries (keeping the currently selected file as the first track).
    - The button icon changes to indicate the current mode (consecutive, repeat, shuffle).
 
+10. **Add**
+    - Opens a file chooser for selecting supported audio files and appends them to the playlist.
+
+11. **Move up**
+    - Moves the selected playlist entry one row up (no-op if it is already the first entry).
+
+12. **Move down**
+    - Moves the selected playlist entry one row down (no-op if it is already the last entry).
+
+13. **Clear**
+    - Stops hrmp if it is running and clears the playlist.
+
 ## Playlist View
 
 You can add one file or multiple files at once, and the order shown reflects the playback order (subject to shuffle mode).
@@ -102,13 +114,23 @@ Below the file list there is a status panel showing the current file playing and
   - **Volume up**: Ctrl++
   - **Play mode** (Once/Repeat/Shuffle): Ctrl+M
   - **Add**: Ctrl+A
-  - **Clear playlist**: Ctrl+L
+  - **Move up**: Alt+Up
+  - **Move down**: Alt+Down
+  - **Clear**: Ctrl+L
 
 These shortcuts complement the hrmp keyboard controls and work regardless of which widget currently has focus inside hrmp-ui.
 
 
 ### File Menu
 
+- **Load**
+  - Opens a file chooser restricted to playlist files (`*.hrmp`).
+  - Replaces the current playlist view with the contents of the selected `.hrmp` file.
+
+- **Save**
+  - Saves the current playlist view to a `.hrmp` file (one filename per line).
+  - A filename is always required; the save dialog supports overwriting an existing file.
+
 - **Quit**
   - Quits hrmp-ui.
   - If hrmp is still running, it is first asked to quit cleanly.

doc/manual/images/ui.png

@@ -1,8 +1,8 @@
 #
 # Add files for hrmp
 #
-FILE(GLOB SOURCE_FILES "libhrmp/*.c")
-FILE(GLOB HEADER_FILES "include/*.h")
+FILE(GLOB SOURCE_FILES CONFIGURE_DEPENDS "libhrmp/*.c")
+FILE(GLOB HEADER_FILES CONFIGURE_DEPENDS "include/*.h")
 
 set(SOURCES ${SOURCE_FILES} ${HEADER_FILES})
 
@@ -173,7 +173,7 @@ add_executable(hrmp-ui
 set_source_files_properties(hrmp-ui-resources.c PROPERTIES GENERATED TRUE)
 
 target_include_directories(hrmp-ui PRIVATE ${GTK3_INCLUDE_DIRS})
-target_link_libraries(hrmp-ui PRIVATE ${GTK3_LIBRARIES})
+target_link_libraries(hrmp-ui PRIVATE hrmp ${GTK3_LIBRARIES})
 target_compile_options(hrmp-ui PRIVATE ${GTK3_CFLAGS_OTHER})
 target_compile_definitions(hrmp-ui PRIVATE HRMP_GTK_VERSION_STRING="${VERSION_STRING}")
 

src/CMakeLists.txt

@@ -89,6 +89,16 @@ hrmp_file_metadata(char* f, struct file_metadata** fm);
 int
 hrmp_print_file_metadata(struct file_metadata* fm);
 
+/**
+ * Check if a file extension is supported by hrmp.
+ * This only checks the filename extension.
+ *
+ * @param filename The filename
+ * @return true if supported, otherwise false
+ */
+bool
+hrmp_file_is_supported(char* filename);
+
 #ifdef __cplusplus
 }
 #endif

src/include/files.h

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2025 The HighResMusicPlayer community
+ *
+ * This program 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.
+ *
+ * This program 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 this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef HRMP_PLAYLIST_H
+#define HRMP_PLAYLIST_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <list.h>
+
+#include <stdbool.h>
+
+/**
+ * Load a playlist file (.hrmp) into an existing files list.
+ *
+ * Each non-empty line can be:
+ *  - Relative file/directory path (relative to the playlist file directory)
+ *  - Absolute file/directory path
+ *  - "*" to add all files in the playlist file directory
+ *  - recursive glob ("**" + "/" + "*")
+ *
+ * @param playlist_path Path to playlist file
+ * @param files Target list to append files to
+ * @param quiet If true, suppress warnings about missing files
+ * @return 0 on success, otherwise 1
+ */
+int
+hrmp_playlist_load(const char* playlist_path, struct list* files, bool quiet);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif