miniradio_server 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70ca64739dfbd93c1badac47fb27cfde9a116c7386284f80becd71c018f091d
-  data.tar.gz: 9232efa32e08339a155806b2e986c93310840c2d4ad48f6f57adb01227463d2c
+  metadata.gz: 656e3006935b38c62d1089e33a604d36887618e1d256cfd366973c55cbbb28b2
+  data.tar.gz: d473daa0a115e3f03719f0a642a5d38e4f4ea91986872ae69b215a3ca3efaaa7
 SHA512:
-  metadata.gz: 2faf237ac46476883a6a5299d5da982d45c9fbb547154871c60587237bde37a6d9b66ae45cd7db2127736d37c7d0e3a8509730e0fd5c51fa12b5fa20e9fc28ed
-  data.tar.gz: 6ae6dabe71bb1d51ba29f60c1c2f2389b1029a9657c19a3e5558c342db6884f5cd1f324762988a62bb39e6e9fb5271ee7f1b83401d6ba4bbe3b3d855b6e93d8d
+  metadata.gz: '05839d4583440e44b8a07340d4c31f441f7441502639f77a63e3bb23c39af1119f8a859f76ea4811c72dfa9e18ea26337cd7c22839583b614c231ccaac80d5fb'
+  data.tar.gz: 9fcdbf122d76f3fd539c2d17422ec1833156af7315e0e19bd43361d64090f47764f149698ea4dc2e74bbcb86f0fd21647c8795a5549b1afe92233b510917426e

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+- Package the `miniradio_server` command, Slim templates, and player assets for
+  installation with RubyGems. Support Ruby 3.4 and later.
+- Configure source/cache directories, port, and FFmpeg through CLI options;
+  requiring the library does not start the server.
+- Stream MP3 files through FFmpeg with persistent HLS caching, safe paths, and
+  support for spaces and Japanese filenames.
+- Provide a shared hls.js player with track metadata, embedded artwork, seeking,
+  volume, previous/next, repeat, and shuffle controls.
+- Verify Ruby style, coverage, player behavior, dependency security, and the
+  installed gem in CI.

data/README.md

@@ -1,124 +1,238 @@
-# Miniradio Server is Simple Ruby HLS Server for MP3s
-This is a basic HTTP Live Streaming (HLS) server written in Ruby using the Rack interface. It serves MP3 audio files by converting them on-the-fly into HLS format (M3U8 playlist and MP3 segment files) using `ffmpeg`. Converted files are cached for subsequent requests.
-This server is designed for simplicity and primarily targets Video on Demand (VOD) scenarios where you want to stream existing MP3 files via HLS without pre-converting them.
-
-## Prerequisites
-Before running the server, ensure you have the following installed:
-1.  **Ruby:** Version 3.1 or later (tested on 3.4).
-2.  **Dependency Gems:** Install using `bundle`.
-3.  **FFmpeg:** A recent version of `ffmpeg` must be installed and accessible in your system's PATH. You can download it from [ffmpeg.org](https://ffmpeg.org/) or install it via your system's package manager (e.g., `apt install ffmpeg`, `brew install ffmpeg`).
-## Setup
-1.  **Install Gems:**
-    ```bash
-    gem install miniradio_server
-    ```
-2.  **Create MP3 Directory:** Create a directory named `mp3_files` in the same location as the script.
-    ```bash
-    mkdir mp3_files
-    ```
-    *(Alternatively, change the `MP3_SRC_DIR` constant in the script).*
-3.  **Add MP3 Files:** Place the MP3 files you want to stream into the `mp3_files` directory.
-    *   **Important:** Use simple, URL-safe filenames for your MP3s (e.g., letters, numbers, underscores, hyphens). Spaces or special characters might cause issues. Example: `my_cool_song.mp3`, `podcast_episode_1.mp3`.
-4.  **Cache Directory:** The script will automatically create a `hls_cache` directory (or the directory specified by `HLS_CACHE_DIR`) when the first conversion occurs. Ensure the script has write permissions in its parent directory.
-
-## Running the Server
-Navigate to the directory containing the script in your terminal and run:
-
-```bash
-bin/miniradio_server
-Info: ffmpeg found.
-Starting HLS conversion and streaming server on port 9292...
-MP3 Source Directory: /path/to/your/project/mp3_files
-HLS Cache Directory: /path/to/your/project/hls_cache
-Default External Encoding: UTF-8
-Using Handler: Rackup::Handler::WEBrick
-Example Streaming URL: http://localhost:9292/stream/{mp3_filename_without_extension}/playlist.m3u8
-e.g., If mp3_files/ contains my_music.mp3 -> http://localhost:9292/stream/my_music/playlist.m3u8
-Press Ctrl+C to stop.
-```
-
-The server will run in the foreground. Press Ctrl+C to stop it.
-
-## Usage: Accessing the Index Page
-
-You can access the index page listing available MP3 files by navigating to `http://localhost:{SERVER_PORT}/` in your web browser.
-
-## Usage: Accessing Streams
+# Miniradio Server
 
-Once the server is running, you can access the HLS streams using an HLS-compatible player (like VLC, QuickTime Player on macOS/iOS, Safari, or web players using hls.js).
+A small Ruby/Rack server that streams existing MP3 files via HTTP Live Streaming
+(HLS). FFmpeg converts each track on its first request; later requests reuse a
+persistent disk cache. This is a VOD server, not a live radio broadcaster.
 
-The URL format is:
+The web player uses one audio element and loads streams only when selected.
+It supports continuous playback, play/pause, previous/next, repeat track, and
+shuffle. All compatible browsers, including Safari, use hls.js for HLS playback.
 
-http\://localhost:{SERVER\_PORT}/stream/{mp3\_filename\_without\_extension}/playlist.m3u8
+## Requirements
 
-**Example:**
+- Ruby 3.4 or later. The repository uses Ruby **4.0.7** via `.ruby-version`;
+  CI also checks the supported minimum Ruby 3.4 series.
+- FFmpeg on `PATH` (`brew install ffmpeg` or `apt install ffmpeg`).
+- Internet access for the web player's Pico CSS and hls.js CDN assets.
+- Node.js 18 or later for player development tests; not needed to run the server.
 
-If you have an MP3 file named mp3\_files/awesome\_track.mp3 and the server is running on the default port 9292, the streaming URL would be:
+## Install and run
 
-http\://localhost:9292/stream/awesome\_track/playlist.m3u8
-
-**Note:** The first time you request a specific stream, the server will run ffmpeg to convert the MP3. This might take a few seconds depending on the file size. Subsequent requests for the same stream will be served instantly from the cache.
-
-## Configuration
-
-You can modify the following constants at the top of the script (miniradio\_server.rb):
+```sh
+gem install miniradio_server -v 0.1.0
+mkdir -p mp3_files
+# Copy your .mp3 files into mp3_files, then:
+miniradio_server
+```
 
-- MP3\_SRC\_DIR: Path to the directory containing your original MP3 files.
-- HLS\_CACHE\_DIR: Path to the directory where HLS segments and playlists will be cached.
-- SERVER\_PORT: The network port the server listens on.
-- FFMPEG\_COMMAND: The command used to execute ffmpeg (change if it's not in your PATH).
-- HLS\_SEGMENT\_DURATION: The target duration (in seconds) for each HLS segment.
+Open <http://localhost:9292/>. Both `mp3_files` and `hls_cache` are created at
+startup in the current working directory. Spaces, Japanese text, and other
+non-ASCII filenames are supported; generated stream links are URL-encoded.
+Only `.mp3` files directly inside the source directory are listed.
 
-## How it Works
+These instructions target version **0.1.0**. Until it is published to RubyGems,
+build and install it from the source checkout using the release preparation
+commands below.
 
-1. A client requests an M3U8 playlist URL (e.g., /stream/my\_song/playlist.m3u8).
-2. The server checks if the corresponding HLS files (hls\_cache/my\_song/playlist.m3u8 and segments) exist in the cache directory.
-3. If the cache does not exist:
-   - It verifies the original mp3\_files/my\_song.mp3 exists.
-   - It acquires a lock specific to my\_song to prevent simultaneous conversions.
-   - It runs ffmpeg to convert my\_song.mp3 into hls\_cache/my\_song/playlist.m3u8 and hls\_cache/my\_song/segmentXXX.mp3.
-   - The lock is released.
-4. If the cache does exist (or after successful conversion), the server serves the requested playlist.m3u8 file.
-5. The client parses the M3U8 playlist and requests the individual MP3 segment files listed within it (e.g., /stream/my\_song/segment000.mp3, /stream/my\_song/segment001.mp3, etc.).
-6. The server serves these segment files directly from the cache directory.
+```sh
+miniradio_server --mp3-dir /path/to/music --cache-dir /path/to/cache --port 9393
+miniradio_server --ffmpeg /path/to/ffmpeg
+miniradio_server --help
+miniradio_server --version
+```
 
-## Limitations
+The server stays in the foreground; press Ctrl+C to stop it. Defaults are port
+9292, `ffmpeg`, and a target HLS segment duration of 10 seconds. Custom Ruby
+applications can instantiate `MiniradioServer::App` with their own directories,
+FFmpeg command, segment duration, and logger. Requiring the library does not
+start a server.
+
+## Playback
+
+The player loads hls.js 1.x from the CDN and requires Media Source Extensions
+(MSE) or Managed Media Source (MMS) with support for the stream's audio codec.
+According to [hls.js compatibility documentation](https://github.com/video-dev/hls.js#compatibility),
+Safari targets include macOS Safari 10+ (macOS 10.11+), iPadOS Safari 13+,
+and iOS Safari 17.1+ (MMS requires hls.js 1.5.0+). These are library targets;
+actual MP3 playback must also be checked on the target device. Older iPhones
+without MMS cannot use this player, even if they support native HLS.
+The player checks `Hls.isSupported()` and displays an error if hls.js is
+unsupported or fails to load; there is no native HLS fallback.
+Remote playback (including AirPlay) is disabled to allow
+[Safari MMS playback without a native alternative](https://webkit.org/blog/14735/webkit-features-in-safari-17-1/).
+
+- The shared player above the track list shows the selected track's title,
+  artist, album, embedded artwork, playback state, and elapsed/total time.
+  Missing tags use the filename or an information-unavailable label; missing
+  artwork uses a placeholder. Selecting a row updates this shared player.
+- The seek bar changes playback position once the duration and seekable range
+  are available. Volume and mute stay unchanged when selecting another track;
+  devices that cannot change volume from the page show a device-control hint.
+- **Play all** starts at the first track and can restart a finished playlist.
+- Each row has a keyboard-accessible play button.
+- **Previous** wraps from the first track to the last. **Next** stops at the end
+  of the list when shuffle is off.
+- **Repeat track** repeats the current track when it ends; it does not loop the
+  entire playlist. Manual previous/next still select another track.
+- **Shuffle** chooses a different random track when there is more than one
+  track, and continues until paused. Repeat track takes precedence on track end.
+- Playback controls are grouped in the shared player; rows only select tracks.
+  When the playlist finishes, the last selected track stays visible. **Play**
+  restarts that track, while **Play all** restarts from the first track.
+
+The first play of a track may take a few seconds while FFmpeg creates its cache.
+An overlapping request for the same conversion receives HTTP 503 with
+`retry-after: 5`. If playback fails, the page displays a message; select the track
+again or press **Retry** to reload it, or press **Play** if the browser blocked
+playback. Track information stays visible when playback is paused or fails.
+
+### Artwork
+
+Only the selected track's artwork is requested, via
+`/artwork/{URL-encoded-filename-without-extension}`. The server returns the
+first eligible embedded JPEG or PNG (up to 5 MiB), with a MIME type determined
+from the binary signature. It does not fetch external covers, search neighboring
+image files, convert images, or create an artwork disk cache. Missing,
+unsupported, oversized, or unreadable artwork returns 404 and shows a placeholder
+without interrupting playback. The size limit bounds the served image, not the
+MP3 parser's memory usage. Unreadable track metadata falls back to the filename
+so one bad tag does not prevent the library from displaying.
+
+## Direct streams and cache
+
+```text
+http://localhost:9292/stream/{URL-encoded-filename-without-extension}/playlist.m3u8
+```
 
-- **VOD Only:** This server is designed for Video on Demand (pre-existing files) and does not support live streaming.
-- **Basic Caching:** Cache is persistent but simple. There's no automatic cache invalidation if the source MP3 changes. You would need to manually clear the corresponding subdirectory in hls\_cache.
-- **Security:** Basic checks against directory traversal are included, but it's not hardened for production use against malicious requests. No authentication/authorization is implemented.
-- **Performance:** Relies on ffmpeg execution per file (first request only). Uses Ruby's WEBrick via rackup, which is single-threaded by default and not ideal for high-concurrency production loads.
-- **Error Handling:** Basic error handling is implemented, but complex ffmpeg issues or edge cases might not be handled gracefully.
-- **Resource Usage:** Conversion can be CPU-intensive (though -c:a copy helps significantly) and disk I/O intensive during the first request for a file.
+For `my song.mp3`, use `/stream/my%20song/playlist.m3u8`. HLS-compatible players
+can request the playlist and the segment URLs it contains directly.
 
+FFmpeg copies the audio codec without re-encoding. Each track gets a cache
+subdirectory containing `playlist.m3u8` and `segmentNNN.mp3` files. Despite their
+extension, the segments use FFmpeg's default HLS MPEG-TS container. The cache
+persists across restarts. Failed conversions are cleaned up and can be retried.
+When a source MP3 changes, manually remove its cache subdirectory while the
+server is stopped; automatic invalidation is not implemented.
 
 ## Development
 
-Install from git repository:
-
-```bash
+```sh
 git clone https://github.com/koichiro/miniradio_server.git
 cd miniradio_server
-bundle
+bin/setup
 bin/miniradio_server
+bundle exec exe/miniradio_server --help
 ```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org/gems/miniradio_server).
-
-## ToDo
-
-* Continuous playback of multiple Music tracks
-* :white_check_mark: ~~Use hls.js to support playback in Chrome.~~
-* :white_check_mark: ~~Rendering of the Delivered Music list page~~
-* :white_check_mark: ~~Multilingual support for file names.~~
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/koichiro/miniradio_server.
+```sh
+bundle exec rake lint         # Standard Ruby style checks
+bundle exec standardrb --fix  # Apply Standard's automatic formatting
+bundle exec rake test         # Ruby tests and the 90% coverage gate
+bundle exec rake test_player  # Player logic tests using Node.js
+bundle exec rake check        # Lint and both test suites (also the default rake task)
+bundle exec rake audit        # Update the advisory database and audit locked gems
+bundle exec rake build        # Build pkg/miniradio_server-0.1.0.gem
+bundle exec rake smoke_gem    # Build/install in a temporary directory and check CLI/assets
+```
 
-## License
+The Ruby suite runs real HLS conversion tests when FFmpeg is installed, and
+skips those tests otherwise. CI installs FFmpeg so conversion tests always run.
+Standard checks Ruby source, tests, executables, and project configuration using
+Ruby 3.4 syntax as the supported minimum; no style violations are grandfathered.
+SimpleCov measures Ruby **line coverage** and fails the test command if the
+overall coverage or any measured source file falls below **90%**. All runtime
+Ruby files under `lib/` are tracked, including files not loaded by tests; only
+the declarative `version.rb` metadata loaded by Bundler before instrumentation
+is excluded. Reports contain the current run only, without merging earlier runs.
+Open `coverage/index.html` for the HTML report or read `coverage/coverage.json`
+for machine-readable results. GitHub Actions runs the same lint/coverage checks
+on Ruby 3.4 and 4.0.7 and uploads each coverage report as an artifact, including
+when tests or the coverage threshold fail.
+Player tests cover control behavior, hls.js readiness, native-capable browsers,
+unavailable hls.js, and URL-encoded Japanese filenames using simulated DOM/media
+APIs. Before releasing, also check actual playback in Safari and Chrome: initial play, rapid track changes, next-track autoplay, pause/resume,
+repeat, shuffle, seeking, and empty libraries. Include Japanese filenames and
+check macOS Safari and iOS/iPadOS Safari on actual devices; simulated player
+tests do not verify decoding or browser autoplay policies.
+
+## Release 0.1.0
+
+Prepare and verify the release artifact:
+
+```sh
+bundle install
+bundle exec rake check
+bundle exec rake audit
+bundle exec rake smoke_gem
+# Install the built artifact for local use:
+gem install ./pkg/miniradio_server-0.1.0.gem --no-document
+miniradio_server --version  # 0.1.0
+```
 
-This project is licensed under the [MIT License](https://opensource.org/licenses/MIT) - see the LICENSE file for details (or assume MIT if no LICENSE file is present).
+The smoke check installs only the built gem into a temporary gem home, using
+runtime dependencies already installed by Bundler. It runs outside the checkout
+and checks the command, version, help, rendered page, JavaScript, and CSS.
+It does not start a listening HTTP server. The package includes runtime files,
+README, changelog, and license; tests, sample MP3s, and local caches are excluded.
+FFmpeg is an external requirement and is not bundled in the gem.
+
+After merging the release PR, complete the browser checks described above and
+run the following from an up-to-date, clean `main` checkout with GitHub push
+access and RubyGems publishing credentials for `miniradio_server`:
+
+```sh
+git switch main
+git pull --ff-only
+bundle install
+bundle exec rake release
+```
 
+Bundler's release task builds the gem, creates the `v0.1.0` Git tag, pushes it
+to the Git remote, and publishes to RubyGems. The gemspec restricts publishing
+to `https://rubygems.org`. Building, running the smoke check, and opening the PR
+do not publish a gem. See [CHANGELOG.md](CHANGELOG.md) for the release contents.
+
+## Dependency security
+
+Dependabot checks Bundler dependencies and GitHub Actions every Monday at 09:00
+Asia/Tokyo and opens update PRs. The existing quality checks and the dependency
+security workflow run on those PRs too. Updates are reviewed and merged manually.
+
+The `Dependency security` workflow runs `bundle exec rake audit` on every PR,
+push to `main`, manual dispatch, and daily at approximately 06:17 Asia/Tokyo.
+Each run refreshes [Ruby Advisory Database](https://github.com/rubysec/ruby-advisory-db)
+and checks the entire `Gemfile.lock`, including runtime, development, and
+transitive gems. Known vulnerabilities, insecure gem sources, or a failed
+database refresh cause the job to fail; advisories are not ignored. Local audits
+also require network access to refresh the database. Results appear in the
+Actions job logs. Scheduled audits catch new advisories even without code changes.
+
+Dependabot **alerts** and **security updates** are separate GitHub repository
+settings; `dependabot.yml` enables version update PRs but cannot enable those
+settings. Under **Settings → Advanced Security** (or **Code security and
+analysis**), enable the dependency graph, Dependabot alerts, and Dependabot
+security updates to receive advisory alerts and automatic security fix PRs.
+See [GitHub's Dependabot documentation](https://docs.github.com/en/code-security/dependabot).
+The Actions audit works independently of those settings. It audits locked Ruby
+gems; browser CDN assets and FFmpeg are not part of `Gemfile.lock`.
+
+## Limitations and next work
+
+- VOD only; no live input, authentication, or authorization.
+- The server is intended for trusted local use. WEBrick binds to its default
+  interface; restrict access with your network configuration when needed.
+- Conversion is synchronous per request. Locks are per process, not shared
+  between multiple server processes.
+- Directory traversal and symlink escapes are rejected, and track metadata is
+  rendered as text. Source/cache directories should remain under your control.
+- No automatic cache invalidation, size limit, or eviction policy.
+- Corrupt or unsupported audio may still fail playback even when its filename
+  is listed using the metadata fallback.
+- Remaining work includes browser playback checks, cache lifecycle management,
+  and improved recovery from conversion/player errors.
+
+## Contributing and license
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/koichiro/miniradio_server).
+Licensed under MIT; see [LICENSE.txt](LICENSE.txt).

data/exe/miniradio_server

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "miniradio_server/cli"
+exit MiniradioServer::CLI.run