v0.4.35: fix Gitea CI (upload-artifact v4 → v3)

The `build` workflow's compile step already passed, but actions/upload-artifact@v4
fails on Gitea's GHES-compatible Actions backend (GHESNotSupportedError: the
@actions/artifact v2 protocol isn't supported), marking every push/tag run red.
Downgrade to @v3 (v1 artifact API, which Gitea implements) so the run goes green.

No mod-code change vs v0.4.34 — version bump only so the latest release carries
the fixed workflow and shows a green check.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

.gitea/workflows/build.yml

@@ -17,7 +17,10 @@ jobs:
           java-version: 25
       - name: Build (MC 26.1.2)
         run: ./gradlew --no-daemon build
-      - uses: actions/upload-artifact@v4
+      # Gitea Actions runs on a GHES-compatible backend that does NOT support the
+      # @actions/artifact v2 protocol (upload-artifact@v4 → GHESNotSupportedError).
+      # v3 uses the v1 artifact API, which Gitea implements — so the run goes green.
+      - uses: actions/upload-artifact@v3
         with:
           name: video_player-mc26.1.2
           path: build/libs/*.jar

gradle.properties

@@ -5,7 +5,7 @@ org.gradle.configuration-cache=false
 
 # Mod
 mod_id=video_player
-mod_version=0.4.24
+mod_version=0.4.35
 maven_group=com.ejclaw.videoplayer
 archives_base_name=video_player
 

src/main/java/com/ejclaw/videoplayer/VideoPlayerClient.java

@@ -3,6 +3,7 @@ package com.ejclaw.videoplayer;
 import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
 import com.ejclaw.videoplayer.client.MusicQuizClient;
 import com.ejclaw.videoplayer.client.net.ClientNetworking;
+import com.ejclaw.videoplayer.client.playback.VideoCache;
 import com.ejclaw.videoplayer.client.playback.VideoPlayback;
 import com.ejclaw.videoplayer.client.render.VideoAnchorRenderer;
 import com.ejclaw.videoplayer.item.VideoStickItem;
@@ -12,6 +13,7 @@ import net.fabricmc.api.ClientModInitializer;
 import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientBlockEntityEvents;
+import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientLifecycleEvents;
 import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents;
 import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
 import net.fabricmc.fabric.api.client.rendering.v1.BlockEntityRendererRegistry;
@@ -82,6 +84,11 @@ public class VideoPlayerClient implements ClientModInitializer {
             }
         });
 
+        // Wipe video_player_cache/ on game exit so preloaded clips don't pile up across
+        // sessions. Cache entries are re-broadcast by the server on every JOIN, so a freshly
+        // started game will repopulate the cache automatically.
+        ClientLifecycleEvents.CLIENT_STOPPING.register(client -> VideoCache.wipeOnShutdown());
+
         VideoPlayerMod.LOG.info("[{}] client initialized", VideoPlayerMod.MOD_ID);
     }
 
@@ -93,17 +100,22 @@ public class VideoPlayerClient implements ClientModInitializer {
      *
      * <p>Gain is also gated by the Minecraft sound options so the in-game sliders work as
      * expected: vanilla {@code SoundEngine.calculateVolume} multiplies by master × category, so
-     * we do the same with {@link SoundSource#PLAYERS} as the category. Result: dragging the
-     * "Players" slider in Options → Music & Sounds attenuates video audio just like other
-     * player sounds, and "Master" still gates everything.
+     * we do the same. The category is configurable via {@code sound_category} in
+     * {@code config/video_player.json} (default {@link SoundSource#RECORDS} = the "Jukebox/Note
+     * Blocks" slider, since video playback is media). Master always gates on top; when the
+     * configured category is Master itself we don't square it. Result: dragging the configured
+     * category's slider in Options → Music &amp; Sounds attenuates video audio, and "Master"
+     * still gates everything.
      */
     private static void updateDistanceGains(Minecraft client) {
         LocalPlayer p = client.player;
         if (p == null || client.level == null) return;
         Vec3 eye = p.getEyePosition();
         float masterVol = client.options.getSoundSourceVolume(SoundSource.MASTER);
-        float playersVol = client.options.getSoundSourceVolume(SoundSource.PLAYERS);
-        float categoryScale = masterVol * playersVol;
+        SoundSource category = VideoPlayerConfig.soundCategory();
+        float categoryScale = (category == SoundSource.MASTER)
+            ? masterVol
+            : masterVol * client.options.getSoundSourceVolume(category);
         for (BlockPos pos : VideoPlayback.activePositions()) {
             if (!(client.level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity be)) continue;
             Vec3 center = be.panelCenter();

src/main/java/com/ejclaw/videoplayer/VideoPlayerConfig.java

@@ -7,6 +7,7 @@ import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
 import net.fabricmc.loader.api.FabricLoader;
+import net.minecraft.sounds.SoundSource;
 
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
@@ -62,10 +63,17 @@ public final class VideoPlayerConfig {
     private static final int DEFAULT_MAX_CACHE_MB = 750;
     /** Default render-distance cap for video anchors, in blocks. 128 = the legacy hard-coded value. */
     private static final int DEFAULT_RENDER_DISTANCE = 128;
+    /**
+     * Default Minecraft sound category the client uses to gate video audio. RECORDS = the
+     * "Jukebox/Note Blocks" (음반) slider — video playback is media, so it belongs there rather
+     * than on the player-sound slider. Master always gates on top of whatever category is set.
+     */
+    private static final SoundSource DEFAULT_SOUND_CATEGORY = SoundSource.RECORDS;
 
     private static volatile int    maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
     private static volatile int    maxCacheMb   = DEFAULT_MAX_CACHE_MB;
     private static volatile int    renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
+    private static volatile SoundSource soundCategory = DEFAULT_SOUND_CATEGORY;
     private static volatile List<String> preloadUrls = Collections.emptyList();
     /** Insertion-ordered name → url. Mutated only under the class monitor. */
     private static final Map<String, String> CACHE_ENTRIES = new LinkedHashMap<>();
@@ -80,6 +88,8 @@ public final class VideoPlayerConfig {
                     VideoPlayerMod.MOD_ID, path);
                 maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
                 maxCacheMb = DEFAULT_MAX_CACHE_MB;
+                renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
+                soundCategory = DEFAULT_SOUND_CATEGORY;
                 preloadUrls = Collections.emptyList();
                 CACHE_ENTRIES.clear();
                 return;
@@ -127,6 +137,23 @@ public final class VideoPlayerConfig {
             if (rd > 2048) rd = 2048;
             renderDistanceBlocks = rd;
 
+            // sound_category (client uses this to pick which volume slider gates video audio)
+            SoundSource cat = DEFAULT_SOUND_CATEGORY;
+            if (json.has("sound_category") && json.get("sound_category").isJsonPrimitive()
+                    && json.get("sound_category").getAsJsonPrimitive().isString()) {
+                SoundSource parsed = parseSoundSource(json.get("sound_category").getAsString());
+                if (parsed != null) {
+                    cat = parsed;
+                } else {
+                    VideoPlayerMod.LOG.warn("[{}] config: unknown sound_category '{}' — using '{}'",
+                        VideoPlayerMod.MOD_ID, json.get("sound_category").getAsString(),
+                        DEFAULT_SOUND_CATEGORY.getName());
+                }
+            } else {
+                augmented = true;
+            }
+            soundCategory = cat;
+
             // preload_urls (legacy)
             List<String> urls = new ArrayList<>();
             if (json.has("preload_urls") && json.get("preload_urls").isJsonArray()) {
@@ -162,9 +189,9 @@ public final class VideoPlayerConfig {
 
             VideoPlayerMod.LOG.info(
                 "[{}] config loaded: per-video={} MB, total-cache={} MB, render={} blocks, "
-                    + "preload_urls={}, cache_entries={}",
+                    + "sound_category={}, preload_urls={}, cache_entries={}",
                 VideoPlayerMod.MOD_ID, maxPreloadMb, maxCacheMb, renderDistanceBlocks,
-                urls.size(), CACHE_ENTRIES.size());
+                soundCategory.getName(), urls.size(), CACHE_ENTRIES.size());
 
             // Auto-augment: rewrite the file once so missing keys appear after a mod update.
             if (augmented) {
@@ -179,11 +206,23 @@ public final class VideoPlayerConfig {
             maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
             maxCacheMb = DEFAULT_MAX_CACHE_MB;
             renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
+            soundCategory = DEFAULT_SOUND_CATEGORY;
             preloadUrls = Collections.emptyList();
             CACHE_ENTRIES.clear();
         }
     }
 
+    /** Match a config string against {@link SoundSource#getName()} (case-insensitive). Null = no match. */
+    private static SoundSource parseSoundSource(String s) {
+        if (s == null) return null;
+        String t = s.trim();
+        if (t.isEmpty()) return null;
+        for (SoundSource src : SoundSource.values()) {
+            if (src.getName().equalsIgnoreCase(t)) return src;
+        }
+        return null;
+    }
+
     // -- accessors ---------------------------------------------------------------------------
 
     /** Hard cap on a single client-side video download, in MB. */
@@ -201,6 +240,12 @@ public final class VideoPlayerConfig {
     /** Anchor BE view-distance cap, in blocks. */
     public static int renderDistanceBlocks() { return renderDistanceBlocks; }
 
+    /**
+     * Minecraft sound category the client gates video audio with (default {@link SoundSource#RECORDS}).
+     * Read client-side from the local config; not pushed from the server.
+     */
+    public static SoundSource soundCategory() { return soundCategory; }
+
     /** Legacy un-named preload list (still pushed at join). Never null. */
     public static List<String> preloadUrls() { return preloadUrls; }
 
@@ -280,11 +325,15 @@ public final class VideoPlayerConfig {
             "max_preload_mb: per-video download cap (each client). "
                 + "max_cache_mb: total cache directory cap (each client). "
                 + "render_distance_blocks: max distance at which a video anchor still renders. "
+                + "sound_category: which Minecraft volume slider gates video audio (client-side). "
+                + "One of: master, music, record, weather, block, hostile, neutral, player, "
+                + "ambient, voice, ui. Default 'record' = the Jukebox/Note Blocks slider. "
                 + "preload_urls: HTTP(S) videos auto-pushed to every player on join (no name). "
                 + "cache_entries: named entries managed by /videoCache add|list|remove.");
         root.addProperty("max_preload_mb", DEFAULT_MAX_PRELOAD_MB);
         root.addProperty("max_cache_mb", DEFAULT_MAX_CACHE_MB);
         root.addProperty("render_distance_blocks", DEFAULT_RENDER_DISTANCE);
+        root.addProperty("sound_category", DEFAULT_SOUND_CATEGORY.getName());
         root.add("preload_urls", new JsonArray());
         root.add("cache_entries", new JsonArray());
         Gson gson = new GsonBuilder().setPrettyPrinting().disableHtmlEscaping().create();
@@ -301,11 +350,15 @@ public final class VideoPlayerConfig {
                 "max_preload_mb: per-video download cap (each client). "
                     + "max_cache_mb: total cache directory cap (each client). "
                     + "render_distance_blocks: max distance at which a video anchor still renders. "
+                    + "sound_category: which Minecraft volume slider gates video audio (client-side). "
+                    + "One of: master, music, record, weather, block, hostile, neutral, player, "
+                    + "ambient, voice, ui. Default 'record' = the Jukebox/Note Blocks slider. "
                     + "preload_urls: legacy un-named auto-preload list. "
                     + "cache_entries: managed by /videoCache add|list|remove.");
             root.addProperty("max_preload_mb", maxPreloadMb);
             root.addProperty("max_cache_mb", maxCacheMb);
             root.addProperty("render_distance_blocks", renderDistanceBlocks);
+            root.addProperty("sound_category", soundCategory.getName());
             JsonArray legacyArr = new JsonArray();
             for (String u : preloadUrls) legacyArr.add(u);
             root.add("preload_urls", legacyArr);

src/main/java/com/ejclaw/videoplayer/client/playback/JavaCvBackend.java

@@ -180,27 +180,24 @@ public class JavaCvBackend implements VideoBackend {
         // stale srcAddr — closing the grabber there frees the av_frame plane and the next
         // memcpy crashes inside StubRoutines::jbyte_disjoint_arraycopy (exactly the 4K-delete
         // crash dump we saw). So the safe rule is: only the decoder thread touches the
-        // grabber. External stop signals `running=false`, stops the audio line, interrupts the
-        // worker, and joins briefly; the worker's own `finally` calls grabber.close(). Inside
-        // the loop, grab() unblocks via the rw_timeout/timeout options (3 s, set in runLoop)
-        // even on a stuck HTTP read, so the join below normally returns within a frame.
+        // grabber. External stop signals `running=false`, stops the audio line, interrupts
+        // the worker, and returns immediately; the worker's own `finally` calls
+        // grabber.close() whenever grab()/start() eventually returns.
+        //
+        // We deliberately do NOT join the worker. close() runs on the client tick thread (via
+        // VideoPlayback.tick → Entry.close), and the worker can spend several seconds inside
+        // the native FFmpeg probe at the top of runLoop — probesize=8 MB and
+        // analyzeduration=2 s do not honor the `running` flag and Thread.interrupt() doesn't
+        // unblock native I/O. A bounded join() there (the old 2 s) is exactly the "place then
+        // immediately delete freezes the game for a moment" symptom: the worker hasn't
+        // entered the grab() loop yet, so flipping running=false has no effect on it until
+        // start() returns. The worker is a daemon, the audio line is already silenced above,
+        // and Entry has been removed from the active map by the caller — nothing observable
+        // depends on the grabber having been closed before this method returns.
         Thread t = worker;
         worker = null;
         if (t != null) {
             t.interrupt();
-            try {
-                t.join(2000);
-            } catch (InterruptedException ie) {
-                Thread.currentThread().interrupt();
-            }
-            if (t.isAlive()) {
-                // Worker still blocked in native grab() — let it finish on its own. Its
-                // finally still closes the grabber when grab() eventually returns / throws.
-                // No native pointers leak in the meantime because we don't touch them here.
-                VideoPlayerMod.LOG.warn(
-                    "[{}] decoder did not exit within 2 s of stop; orphaning until next grab() returns",
-                    VideoPlayerMod.MOD_ID);
-            }
         }
         ready = false;
     }
@@ -279,6 +276,14 @@ public class JavaCvBackend implements VideoBackend {
             Class<?> frameCls    = Class.forName(FRAME_CLASS);
             Field imageField     = frameCls.getField("image");
             Field samplesField   = frameCls.getField("samples");
+            // Row stride (bytes) of frame.image[0]. swscale aligns the RGBA linesize to a SIMD
+            // boundary (32/64 B), so for any width whose width*4 isn't already aligned the plane
+            // is padded: e.g. 1674-wide → linesize 6720 instead of 6696. We read this to strip
+            // the padding row-by-row; resolved defensively so a Frame without the field just
+            // falls back to deriving the stride from the buffer size below.
+            Field strideField;
+            try { strideField = frameCls.getField("imageStride"); }
+            catch (Throwable t) { strideField = null; }
             // Java2DFrameConverter is no longer used now that we read RGBA bytes directly,
             // but we still resolve its class so a future code path could fall back to it if a
             // grabber refuses setPixelFormat. Keep the lookup defensive.
@@ -326,26 +331,40 @@ public class JavaCvBackend implements VideoBackend {
                     // primary memory-churn problem; 0.4.10 fixed that; 0.4.11 adds the ring on
                     // top to absorb the burst-then-stall caused by SourceDataLine backpressure
                     // pacing only at audio-buffer granularity.
-                    int need = src.remaining();
-                    // Reviewer-mandated sanity bounds: memCopy is a raw native copy with no
-                    // fence against overrun. Validate against (a) the source buffer's own
-                    // capacity (so a corrupt plane can't read past it) and (b) the expected
-                    // RGBA frame size (width*height*4) (so an unexpectedly oversized plane
-                    // can't smash the dst slot we'll allocate). If either fails, skip this
-                    // frame and continue — the next grab() will give us a fresh one.
-                    int expected = width * height * 4;
-                    if (need > src.capacity()) {
-                        VideoPlayerMod.LOG.warn("[{}] frame overruns source capacity (need={}, cap={}); skipping",
-                            VideoPlayerMod.MOD_ID, need, src.capacity());
-                        need = 0;
-                    } else if (need > expected) {
-                        VideoPlayerMod.LOG.warn("[{}] frame larger than expected RGBA size (need={}, expected={}); skipping",
-                            VideoPlayerMod.MOD_ID, need, expected);
-                        need = 0;
+                    // The destination texture is tightly packed: one frame = width*height*4
+                    // bytes with no row padding (consumeFrame copies ringBytes[idx] straight
+                    // into a w*h*4 GPU texture and rejects anything larger). swscale, however,
+                    // hands us an RGBA plane whose linesize is SIMD-aligned, so for any width
+                    // where width*4 isn't a multiple of the alignment the source rows carry
+                    // trailing padding (e.g. 1674-wide → 6720 B/row vs the 6696 B we want).
+                    // Copying the padded buffer verbatim both overruns the tight dst slot and
+                    // shears the image; we must strip the pad row-by-row.
+                    int rowBytes = width * 4;            // bytes of real pixels per row
+                    int dstBytes = rowBytes * height;    // tightly-packed frame size
+                    // Source row stride: prefer Frame.imageStride (authoritative), else derive
+                    // it from the buffer size. Guard against a stride smaller than a full row
+                    // (bogus field) by falling back to the tight rowBytes.
+                    int strideBytes = rowBytes;
+                    if (strideField != null) {
+                        try {
+                            int s = strideField.getInt(frame);
+                            if (s >= rowBytes) strideBytes = s;
+                        } catch (Throwable ignored) {}
+                    } else if (height > 0) {
+                        int s = src.remaining() / height;
+                        if (s >= rowBytes) strideBytes = s;
                     }
-                    if (need > 0) {
+                    // Sanity bound: the strided read must stay within the source buffer. memCopy
+                    // is a raw native copy with no overrun fence, so if the plane is smaller than
+                    // stride*height (corrupt/truncated) skip this frame and grab a fresh one.
+                    boolean ok = dstBytes > 0 && (long) strideBytes * height <= src.capacity();
+                    if (!ok && dstBytes > 0) {
+                        VideoPlayerMod.LOG.warn("[{}] frame plane too small (stride={}, h={}, cap={}); skipping",
+                            VideoPlayerMod.MOD_ID, strideBytes, height, src.capacity());
+                    }
+                    if (ok) {
                         int srcPos = src.position();
-                        long srcAddr = MemoryUtil.memAddress(src) + srcPos;
+                        long srcBase = MemoryUtil.memAddress(src) + srcPos;
                         synchronized (frameLock) {
                             // Recheck shutdown inside the lock: stopWorker() flipped running=false
                             // before signaling, so worker is the only writer here and grabber.close()
@@ -353,12 +372,21 @@ public class JavaCvBackend implements VideoBackend {
                             // the contract obvious to future readers.
                             if (!running.get() || closed) break;
                             int idx = ringTail;
-                            if (ringBufs[idx] == null || ringBufs[idx].capacity() < need) {
-                                ringBufs[idx] = ByteBuffer.allocateDirect(need).order(ByteOrder.nativeOrder());
+                            if (ringBufs[idx] == null || ringBufs[idx].capacity() < dstBytes) {
+                                ringBufs[idx] = ByteBuffer.allocateDirect(dstBytes).order(ByteOrder.nativeOrder());
                             }
-                            long dstAddr = MemoryUtil.memAddress(ringBufs[idx]);
-                            MemoryUtil.memCopy(srcAddr, dstAddr, need);
-                            ringBytes[idx] = need;
+                            long dstBase = MemoryUtil.memAddress(ringBufs[idx]);
+                            if (strideBytes == rowBytes) {
+                                MemoryUtil.memCopy(srcBase, dstBase, dstBytes);
+                            } else {
+                                // Strip swscale row padding: copy only the real pixels per row.
+                                for (int y = 0; y < height; y++) {
+                                    MemoryUtil.memCopy(srcBase + (long) y * strideBytes,
+                                                       dstBase + (long) y * rowBytes,
+                                                       rowBytes);
+                                }
+                            }
+                            ringBytes[idx] = dstBytes;
                             ringTail = (idx + 1) % FRAME_RING_SLOTS;
                             if (ringCount < FRAME_RING_SLOTS) {
                                 ringCount++;

src/main/java/com/ejclaw/videoplayer/client/playback/VideoCache.java

@@ -52,6 +52,18 @@ public final class VideoCache {
      */
     private static final AtomicLong CACHE_EPOCH = new AtomicLong(0);
 
+    /**
+     * Per-URL cancellation channel for {@link #purge(String)}. The global {@link #CACHE_EPOCH}
+     * can only cancel <em>all</em> in-flight downloads at once; a targeted purge needs to stop
+     * exactly one. Each submitted download captures a unique generation here at submit time;
+     * {@link #purge(String)} removes the URL's entry, which makes the running download's
+     * {@link #cancelled(String, long, long)} checks (read loop + every publish point) fail and
+     * self-clean its {@code .part}/promoted file instead of re-publishing post-purge.
+     */
+    private static final Map<String, Long> DOWNLOAD_GEN = new ConcurrentHashMap<>();
+    /** Monotonic source for per-download generations stored in {@link #DOWNLOAD_GEN}. */
+    private static final AtomicLong GEN_SEQ = new AtomicLong(0);
+
     /**
      * Single-thread executor that serializes all downloads. Cap enforcement (the total
      * cache size check) needs an authoritative view of the cache directory at the moment a
@@ -103,6 +115,12 @@ public final class VideoCache {
     /** Server-driven delete of a cached URL. Removes from READY and from disk. */
     public static void purge(String url) {
         if (url == null || url.isEmpty()) return;
+        // Cancel any in-flight download of this exact URL first. Dropping its generation
+        // makes the download thread's cancelled() checks fail, so it deletes its own .part
+        // (or rolls back a just-promoted file) instead of finishing and re-publishing after
+        // we've purged. Without this, a slow/large download evicted mid-flight would silently
+        // reappear on disk + in READY once it completed.
+        DOWNLOAD_GEN.remove(url);
         Path p = READY.remove(url);
         if (p == null) {
             // Not in this session's index, but the file may still be on disk from a prior run.
@@ -158,6 +176,7 @@ public final class VideoCache {
         // Phase 2: drop indexes.
         READY.clear();
         IN_FLIGHT.clear();
+        DOWNLOAD_GEN.clear();
 
         // Phase 3: delete files on disk.
         int deleted = 0;
@@ -209,7 +228,11 @@ public final class VideoCache {
         // CACHE_EPOCH later — any mismatch means clearAll() ran in between and this
         // download must abort without publishing.
         long epoch = CACHE_EPOCH.get();
-        DOWNLOAD_POOL.submit(() -> download(url, epoch));
+        // Register a unique generation for this download so a targeted purge() can cancel
+        // exactly this URL (see DOWNLOAD_GEN / cancelled()).
+        long gen = GEN_SEQ.incrementAndGet();
+        DOWNLOAD_GEN.put(url, gen);
+        DOWNLOAD_POOL.submit(() -> download(url, epoch, gen));
     }
 
     /** Return the local cached file path for this URL, or {@code null} if not yet ready. */
@@ -224,6 +247,42 @@ public final class VideoCache {
     public static void clearIndex() {
         READY.clear();
         IN_FLIGHT.clear();
+        DOWNLOAD_GEN.clear();
+    }
+
+    /**
+     * Wipe the cache directory at game shutdown so the user doesn't accumulate disk usage
+     * across sessions. Distinct from {@link #clearAll()}: at shutdown there are no concurrent
+     * downloads to race and no player to chat-notify, so we skip the chat ping but still bump
+     * the epoch (defensive — any straggler write inside the in-flight {@code .part} stream
+     * will detect the bump and self-clean) and drop indexes.
+     */
+    public static void wipeOnShutdown() {
+        CACHE_EPOCH.incrementAndGet();
+        READY.clear();
+        IN_FLIGHT.clear();
+        DOWNLOAD_GEN.clear();
+        int deleted = 0;
+        int failed  = 0;
+        try {
+            Path dir = cacheDir();
+            if (dir != null && Files.isDirectory(dir)) {
+                try (var stream = Files.newDirectoryStream(dir)) {
+                    for (Path p : stream) {
+                        try {
+                            if (Files.isRegularFile(p) && Files.deleteIfExists(p)) deleted++;
+                        } catch (Throwable t) {
+                            failed++;
+                        }
+                    }
+                }
+            }
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] wipeOnShutdown failed: {}",
+                VideoPlayerMod.MOD_ID, t.toString());
+        }
+        VideoPlayerMod.LOG.info("[{}] wipeOnShutdown: deleted={} failed={}",
+            VideoPlayerMod.MOD_ID, deleted, failed);
     }
 
     /** Caller-supplied: current set of URLs that are fully cached, for diagnostics. */
@@ -249,10 +308,16 @@ public final class VideoCache {
      * @return {@code true} if the entry is now published; {@code false} if the
      *         caller's work was cancelled and {@code path} has been cleaned up.
      */
-    private static boolean publishIfNotCancelled(String url, Path path, long startEpoch) {
-        if (CACHE_EPOCH.get() != startEpoch) return false;
+    private static boolean publishIfNotCancelled(String url, Path path, long startEpoch, long startGen) {
+        // If a wipe (clearAll) or a targeted purge ran between download's pre-move check and
+        // Files.move, its directory scan won't have seen this just-promoted file. We must
+        // delete it here, not just bail — otherwise the freshly-moved final file leaks.
+        if (cancelled(url, startEpoch, startGen)) {
+            try { Files.deleteIfExists(path); } catch (Throwable ignored) {}
+            return false;
+        }
         READY.put(url, path);
-        if (CACHE_EPOCH.get() != startEpoch) {
+        if (cancelled(url, startEpoch, startGen)) {
             READY.remove(url, path);
             try { Files.deleteIfExists(path); } catch (Throwable ignored) {}
             return false;
@@ -260,7 +325,19 @@ public final class VideoCache {
         return true;
     }
 
-    private static void download(String url, long startEpoch) {
+    /**
+     * True if the in-flight download for {@code url} should abort and self-clean. Two channels:
+     * a global wipe ({@link #clearAll()}/{@link #wipeOnShutdown()} bumped {@link #CACHE_EPOCH}),
+     * or a targeted {@link #purge(String)} that removed/replaced this URL's generation in
+     * {@link #DOWNLOAD_GEN}.
+     */
+    private static boolean cancelled(String url, long startEpoch, long startGen) {
+        if (CACHE_EPOCH.get() != startEpoch) return true;
+        Long cur = DOWNLOAD_GEN.get(url);
+        return cur == null || cur.longValue() != startGen;
+    }
+
+    private static void download(String url, long startEpoch, long startGen) {
         Path cacheDir = cacheDir();
         Path partPath = null;
         try {
@@ -271,8 +348,8 @@ public final class VideoCache {
             }
             // Pre-flight cancellation check — if clearAll already ran between submit and now,
             // skip the whole thing. Avoids creating directories / .part files post-clear.
-            if (CACHE_EPOCH.get() != startEpoch) {
-                VideoPlayerMod.LOG.info("[{}] preload: cancelled before start (clearAll ran) — {}",
+            if (cancelled(url, startEpoch, startGen)) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled before start (clearAll/purge ran) — {}",
                     VideoPlayerMod.MOD_ID, url);
                 return;
             }
@@ -286,8 +363,8 @@ public final class VideoCache {
             // Resume-friendly: if the file's already on disk from an earlier session, just
             // index it without re-downloading.
             if (Files.exists(finalPath) && Files.size(finalPath) > 0) {
-                if (!publishIfNotCancelled(url, finalPath, startEpoch)) {
-                    VideoPlayerMod.LOG.info("[{}] preload: reindex cancelled (clearAll ran) — {}",
+                if (!publishIfNotCancelled(url, finalPath, startEpoch, startGen)) {
+                    VideoPlayerMod.LOG.info("[{}] preload: reindex cancelled (clearAll/purge ran) — {}",
                         VideoPlayerMod.MOD_ID, url);
                     return;
                 }
@@ -338,7 +415,7 @@ public final class VideoCache {
                     // Cancellation check inside the loop. Break (not return) so the try-with
                     // closes the output stream first — on Windows, deleting an open .part can
                     // fail with AccessDeniedException, so we always close before deleting.
-                    if (CACHE_EPOCH.get() != startEpoch) {
+                    if (cancelled(url, startEpoch, startGen)) {
                         cancelled = true;
                         break;
                     }
@@ -376,8 +453,8 @@ public final class VideoCache {
 
             // Pre-move cancellation check. If clearAll ran during the read loop, abort
             // before promoting .part to final — saves a wasted move + delete.
-            if (CACHE_EPOCH.get() != startEpoch) {
-                VideoPlayerMod.LOG.info("[{}] preload: cancelled before move (clearAll ran) — {}",
+            if (cancelled(url, startEpoch, startGen)) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled before move (clearAll/purge ran) — {}",
                     VideoPlayerMod.MOD_ID, url);
                 try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
                 return;
@@ -391,8 +468,8 @@ public final class VideoCache {
             // the window between READY.put and the "완료" notification (clearAll wipes
             // READY then we re-publish + emit stale completion chat). publishIfNotCancelled
             // rolls back both READY and the on-disk file if the epoch moved at any time.
-            if (!publishIfNotCancelled(url, finalPath, startEpoch)) {
-                VideoPlayerMod.LOG.info("[{}] preload: cancelled at publish (clearAll ran) — {}",
+            if (!publishIfNotCancelled(url, finalPath, startEpoch, startGen)) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled at publish (clearAll/purge ran) — {}",
                     VideoPlayerMod.MOD_ID, url);
                 return;
             }
@@ -411,6 +488,9 @@ public final class VideoCache {
             }
         } finally {
             IN_FLIGHT.remove(url);
+            // Only clear our own generation — a re-preload after a purge may have installed a
+            // newer gen for this URL that must survive.
+            DOWNLOAD_GEN.remove(url, startGen);
         }
     }
 

src/main/java/com/ejclaw/videoplayer/command/CommandPermissions.java

@@ -0,0 +1,45 @@
+package com.ejclaw.videoplayer.command;
+
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.server.permissions.Permissions;
+import net.minecraft.world.entity.player.Player;
+
+/**
+ * Shared {@code .requires(...)} predicate for all {@code /video*} commands.
+ *
+ * <p>Semantics:
+ * <ul>
+ *   <li><b>Player source</b> — must be OP (permission level ≥ 2, via
+ *       {@link Permissions#COMMANDS_GAMEMASTER}). Non-OP players don't even see the command
+ *       in tab-completion.</li>
+ *   <li><b>Non-player source</b> — server console, command block, and datapack
+ *       {@code /function} are always allowed regardless of any permission level
+ *       or gamerule. This means admins don't need to bump {@code functionPermissionLevel}
+ *       just to drive {@code /videoPlace} etc. from a datapack function.</li>
+ * </ul>
+ *
+ * <p>The bypass for non-player sources is safe because reaching one of those execution
+ * contexts already requires server-operator trust:
+ * <ul>
+ *   <li>Console — physical/admin access to the server.</li>
+ *   <li>Command block — placing one requires OP + {@code /gamerule sendCommandFeedback}
+ *       privileges, and {@code /execute as} preserves the underlying source's permissions
+ *       (so a non-OP player can't smuggle commands through one).</li>
+ *   <li>Datapack function — installed by the server admin.</li>
+ * </ul>
+ */
+public final class CommandPermissions {
+    private CommandPermissions() {}
+
+    /**
+     * Returns {@code true} when the source is allowed to run a {@code /video*} command.
+     *
+     * <p>Player → OP only. Anything else → always allowed.
+     */
+    public static boolean opOrServer(CommandSourceStack s) {
+        if (s.getEntity() instanceof Player) {
+            return s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER);
+        }
+        return true;
+    }
+}

src/main/java/com/ejclaw/videoplayer/command/VideoCacheCommand.java

@@ -20,7 +20,6 @@ import net.minecraft.network.chat.MutableComponent;
 import net.minecraft.network.chat.Style;
 import net.minecraft.server.MinecraftServer;
 import net.minecraft.server.level.ServerPlayer;
-import net.minecraft.server.permissions.Permissions;
 
 import java.net.URI;
 import java.util.Map;
@@ -32,8 +31,9 @@ import java.util.Map;
  * <br>{@code /videocache remove <name>} — drop the entry from server config and tell every client
  * to delete the matching cache file.
  *
- * <p>Replaces the old {@code /videopreload}. Same permission gate
- * ({@link Permissions#COMMANDS_GAMEMASTER}) so command blocks can drive it.
+ * <p>Replaces the old {@code /videopreload}. Permission gate via
+ * {@link CommandPermissions#opOrServer(CommandSourceStack)} so command blocks and datapack
+ * functions can drive it without touching {@code functionPermissionLevel}.
  */
 public final class VideoCacheCommand {
     private VideoCacheCommand() {}
@@ -44,7 +44,7 @@ public final class VideoCacheCommand {
 
     private static LiteralArgumentBuilder<CommandSourceStack> build(String root) {
         return Commands.literal(root)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.literal("add")
                 .then(Commands.argument("name", StringArgumentType.word())
                     .then(Commands.argument("url", StringArgumentType.greedyString())

src/main/java/com/ejclaw/videoplayer/command/VideoDeleteCommand.java

@@ -9,7 +9,6 @@ import net.minecraft.commands.arguments.coordinates.BlockPosArgument;
 import net.minecraft.core.BlockPos;
 import net.minecraft.network.chat.Component;
 import net.minecraft.server.level.ServerLevel;
-import net.minecraft.server.permissions.Permissions;
 import net.minecraft.world.level.block.Block;
 import net.minecraft.world.level.block.Blocks;
 
@@ -24,7 +23,7 @@ public final class VideoDeleteCommand {
     private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
     build(String name) {
         return Commands.literal(name)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.argument("pos", BlockPosArgument.blockPos())
                 .executes(VideoDeleteCommand::run));
     }

src/main/java/com/ejclaw/videoplayer/command/VideoMuteCommand.java

@@ -14,7 +14,6 @@ import net.minecraft.core.BlockPos;
 import net.minecraft.network.chat.Component;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
-import net.minecraft.server.permissions.Permissions;
 
 /** SPEC §4.5.1 — {@code /videoMute <pos> <on|off>} */
 public final class VideoMuteCommand {
@@ -27,7 +26,7 @@ public final class VideoMuteCommand {
     private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
     build(String name) {
         return Commands.literal(name)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.argument("pos", BlockPosArgument.blockPos())
                 .then(Commands.argument("state", StringArgumentType.word())
                     .executes(VideoMuteCommand::run)));

src/main/java/com/ejclaw/videoplayer/command/VideoPlaceCommand.java

@@ -19,13 +19,32 @@ import net.minecraft.nbt.CompoundTag;
 import net.minecraft.network.chat.Component;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
-import net.minecraft.server.permissions.Permissions;
 import net.minecraft.world.level.block.Block;
 
-/** SPEC §4.5.1 — {@code /videoPlace <pos> <facing> <width> <height> <url>} */
+/**
+ * SPEC §4.5.1 — {@code /videoPlace} has two accepted forms:
+ *
+ * <ul>
+ *   <li><b>Legacy 5-arg</b>: {@code /videoPlace <pos> <facing> <width> <height> <url>}
+ *       — preserved for existing command blocks. Volume defaults to 50% and muted=false.
+ *       The {@code url} here is a single-token string so it doesn't swallow the {@code volume}
+ *       slot of the new form.</li>
+ *   <li><b>New 6-arg</b>: {@code /videoPlace <pos> <facing> <width> <height> <volume> <url>}
+ *       — {@code volume} is 0..100 (percent) or {@code -1} to start muted. The percent form
+ *       mirrors the GUI slider; {@code -1} is a CLI shortcut so admins don't need a follow-up
+ *       {@code /videoMute} step. {@code url} is greedy here, so URLs containing spaces (rare
+ *       but possible after URL-decoding) still work.</li>
+ * </ul>
+ *
+ * <p>Brigadier disambiguates the two by the type of the 5th argument: integer → new form,
+ * non-integer token → legacy form.
+ */
 public final class VideoPlaceCommand {
     private VideoPlaceCommand() {}
 
+    /** Default volume (percent) applied to the legacy 5-arg form. */
+    private static final int DEFAULT_VOLUME_PCT = 50;
+
     public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
         dispatcher.register(build("videoPlace"));
     }
@@ -33,17 +52,38 @@ public final class VideoPlaceCommand {
     private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
     build(String name) {
         return Commands.literal(name)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.argument("pos", BlockPosArgument.blockPos())
                 .then(Commands.argument("facing", StringArgumentType.word())
                     .then(Commands.argument("width", IntegerArgumentType.integer(1, 32))
                         .then(Commands.argument("height", IntegerArgumentType.integer(1, 32))
+                            // New form: volume (int) + greedy url
+                            .then(Commands.argument("volume", IntegerArgumentType.integer(-1, 100))
                                 .then(Commands.argument("url", StringArgumentType.greedyString())
-                                .executes(VideoPlaceCommand::run))))));
+                                    .executes(ctx -> runNew(ctx))))
+                            // Legacy form: single-token url, no volume slot. Single-token string
+                            // is intentional so "<int> https://..." cannot be parsed as a legacy
+                            // url that happens to start with a number — Brigadier first tries the
+                            // new branch and only falls through here if "volume" isn't an int.
+                            .then(Commands.argument("url", StringArgumentType.string())
+                                .executes(ctx -> runLegacy(ctx)))))));
     }
 
-    private static int run(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+    private static int runNew(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
             throws CommandSyntaxException {
+        int volumeArg = IntegerArgumentType.getInteger(ctx, "volume");
+        String url = StringArgumentType.getString(ctx, "url");
+        return runWithValues(ctx, volumeArg, url);
+    }
+
+    private static int runLegacy(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+            throws CommandSyntaxException {
+        String url = StringArgumentType.getString(ctx, "url");
+        return runWithValues(ctx, DEFAULT_VOLUME_PCT, url);
+    }
+
+    private static int runWithValues(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx,
+                                     int volumeArg, String rawUrl) throws CommandSyntaxException {
         CommandSourceStack src = ctx.getSource();
         ServerLevel level = src.getLevel();
         BlockPos pos = BlockPosArgument.getLoadedBlockPos(ctx, "pos");
@@ -54,7 +94,12 @@ public final class VideoPlaceCommand {
         }
         int width  = IntegerArgumentType.getInteger(ctx, "width");
         int height = IntegerArgumentType.getInteger(ctx, "height");
-        String raw = StringArgumentType.getString(ctx, "url").trim();
+        // -1 is the CLI mute shortcut; the BE keeps the underlying volume so an admin can
+        // /videoMute false later without re-typing a level. Anything 0..100 sets %-volume and
+        // clears mute.
+        boolean placeMuted = volumeArg < 0;
+        float placeVolume = placeMuted ? 0.5F : (volumeArg / 100.0F);
+        String raw = rawUrl == null ? "" : rawUrl.trim();
         // Accept either an http(s) URL or a /videoCache add <name> entry: resolveUrlOrName()
         // returns the canonical URL in both cases, or null when a non-URL string didn't match
         // any named entry.
@@ -75,6 +120,8 @@ public final class VideoPlaceCommand {
         be.setWidth(width);
         be.setHeight(height);
         be.setUrl(url);
+        be.setVolume(placeVolume);
+        be.setMuted(placeMuted);
 
         CompoundTag nbt = be.toNbt();
         for (ServerPlayer p : PlayerLookup.tracking(level, pos)) {

src/main/java/com/ejclaw/videoplayer/command/VideoStickCommand.java

@@ -12,7 +12,11 @@ public final class VideoStickCommand {
     private VideoStickCommand() {}
 
     public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
+        // 플레이어는 OP(level 2+) 만, 콘솔/커맨드블럭/함수(/function) 는 무조건 통과.
+        // 따라서 functionPermissionLevel 같은 gamerule 을 만질 필요가 없다.
+        // 일반 플레이어(level 0) 는 탭 자동완성에도 안 떠야 정상.
         dispatcher.register(Commands.literal("videoStick")
+            .requires(CommandPermissions::opOrServer)
             .executes(ctx -> run(ctx.getSource())));
     }