feat: Update environment variables and Docker configuration for cache management and temporary directory settings

.env.example

@@ -12,10 +12,11 @@ ABOGEN_OUTPUT_DIR=./storage/output
 
 # Temporary working directory. When running in Docker, keep this inside the
 # mounted data volume (or another writable host path) so non-root users can
-# write to it. Hugging Face caches and other temp files are redirected here via
+# write to it. Only audio conversion scratch files are staged here by default;
-# XDG_CACHE_HOME/HF_HOME when running under Docker. For local (non-Docker)
+# other library caches remain inside the container volume. For local
-# usage, change this to a path that makes sense on your machine or comment it
+# (non-Docker) usage, change this to a path that makes sense on your machine or
-# out to fall back to the OS cache directory. Mounted to /data/cache in Docker.
+# comment it out to fall back to the OS cache directory. Mounted to /data/cache
+# in Docker.
 ABOGEN_TEMP_DIR=./storage/tmp
 
 # UID/GID used when running the Docker container. 1000:1000 matches most Linux hosts.

README.md

@@ -52,11 +52,7 @@ Browse to http://localhost:8808. Uploaded source files are stored in `/data/uplo
 | `ABOGEN_OUTPUT_ROOT` | `/data/outputs` | Directory for generated audio and subtitles (legacy alias of `ABOGEN_OUTPUT_DIR`) |
 | `ABOGEN_OUTPUT_DIR` | `/data/outputs` | Container path for rendered audio/subtitles |
 | `ABOGEN_SETTINGS_DIR` | `/config` | Container path for JSON settings/configuration |
-| `ABOGEN_TEMP_DIR` | `/data/cache` (Docker) or platform cache dir | Container path for temporary files |
+| `ABOGEN_TEMP_DIR` | `/data/cache` (Docker) or platform cache dir | Container path for temporary audio working files |
-| `XDG_CACHE_HOME` | `/data/cache` | Base directory for cache data (used by many Python libraries) |
-| `HF_HOME` | `/data/cache/huggingface` | Hugging Face model cache directory |
-| `HUGGINGFACE_HUB_CACHE` | `/data/cache/huggingface` | Alias for Hugging Face hub cache |
-| `TRANSFORMERS_CACHE` | `/data/cache/huggingface` | Transformers model cache directory |
 | `ABOGEN_UID` | `1000` | UID that the container should run as (matches host user) |
 | `ABOGEN_GID` | `1000` | GID that the container should run as (matches host group) |
 
@@ -75,11 +71,11 @@ When running via Docker Compose, set `ABOGEN_SETTINGS_DIR`,
 `ABOGEN_OUTPUT_DIR`, and `ABOGEN_TEMP_DIR` in your `.env` file to the host
 directories you want mounted into the container. Compose maps them to
 `/config`, `/data/outputs`, and `/data/cache` respectively while exporting
-those in-container paths to the application. The cache mount is also shared
+those in-container paths to the application. Non-audio caches (e.g., Hugging
-with common environment variables (`XDG_CACHE_HOME`, `HF_HOME`,
+Face downloads) stick to the container's internal cache under `/tmp/abogen-home/.cache`
-`HUGGINGFACE_HUB_CACHE`, `TRANSFORMERS_CACHE`) so libraries like Hugging Face
+by default, so only conversion scratch data touches the mounted `ABOGEN_TEMP_DIR`.
-store downloads in the same writable location. Ensure each host directory exists
+Ensure each host directory exists and is writable by the UID/GID you configure
-and is writable by the UID/GID you configure before starting the stack.
+before starting the stack.
 
 ### Docker Compose (GPU by default)
 The repo includes `docker-compose.yaml`, which targets GPU hosts out of the box. Install the NVIDIA Container Toolkit and run:

abogen/Dockerfile

@@ -34,7 +34,7 @@ RUN pip install --upgrade pip \
      else \
        pip install torch torchvision torchaudio --index-url "$TORCH_INDEX_URL"; \
      fi \
-  && pip install --no-cache-dir .
+  && pip install --no-cache-dir . en-core-web-sm==3.8.0
 
 ENV ABOGEN_HOST=0.0.0.0 \
   ABOGEN_PORT=8808

abogen/utils.py

@@ -158,19 +158,31 @@ def get_user_cache_root():
         if last_error is not None:
             raise last_error
 
-    def _configure_cache_env(cache_path):
+    def _configure_cache_env():
-        os.environ.setdefault("XDG_CACHE_HOME", cache_path)
+        home_dir = os.environ.get("HOME")
+        if not home_dir:
+            home_dir = ensure_directory(os.path.join("/tmp", "abogen-home"))
+            os.environ["HOME"] = home_dir
+        else:
+            home_dir = ensure_directory(home_dir)
 
-        hf_cache = os.path.join(cache_path, "huggingface")
+        cache_base = os.environ.get("XDG_CACHE_HOME")
-        for env_var in ("HF_HOME", "HUGGINGFACE_HUB_CACHE", "TRANSFORMERS_CACHE"):
+        if cache_base:
+            cache_base = ensure_directory(cache_base)
+        else:
+            cache_base = ensure_directory(os.path.join(home_dir, ".cache"))
+            os.environ["XDG_CACHE_HOME"] = cache_base
+
+        hf_cache = os.environ.get("HF_HOME")
+        if hf_cache:
+            hf_cache = ensure_directory(hf_cache)
+        else:
+            hf_cache = ensure_directory(os.path.join(cache_base, "huggingface"))
+            os.environ["HF_HOME"] = hf_cache
+
+        for env_var in ("HUGGINGFACE_HUB_CACHE", "TRANSFORMERS_CACHE"):
             os.environ.setdefault(env_var, hf_cache)
 
-        # Ensure Hugging Face cache directory exists so downloads succeed.
-        ensure_directory(hf_cache)
-
-        if not os.environ.get("HOME"):
-            os.environ["HOME"] = os.path.dirname(cache_path) or "/"
-
     cache_root = None
 
     override = os.environ.get("ABOGEN_TEMP_DIR")
@@ -201,7 +213,7 @@ def get_user_cache_root():
             logger.warning("Falling back to temp cache directory %s", tmp_candidate)
             cache_root = ensure_directory(tmp_candidate)
 
-    _configure_cache_env(cache_root)
+    _configure_cache_env()
     return cache_root
 
 

docker-compose.yaml

@@ -23,11 +23,7 @@ services:
       ABOGEN_OUTPUT_DIR: "/data/outputs"
       ABOGEN_OUTPUT_ROOT: "/data/outputs"
       ABOGEN_TEMP_DIR: "/data/cache"
-      HOME: "/data"
+      HOME: "/tmp/abogen-home"
-      XDG_CACHE_HOME: "/data/cache"
-      HF_HOME: "/data/cache/huggingface"
-      HUGGINGFACE_HUB_CACHE: "/data/cache/huggingface"
-      TRANSFORMERS_CACHE: "/data/cache/huggingface"
     # --- GPU support -----------------------------------------------------
     # These settings assume the NVIDIA Container Toolkit is installed.
     # Leave them in place for GPU acceleration; comment out the entire block

pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
     "misaki[zh]>=0.9.4",
     "ebooklib>=0.19",
     "beautifulsoup4>=4.13.4",
+    "en-core-web-sm==3.8.0",
     "PyMuPDF>=1.25.5",
     "platformdirs>=4.3.7",
     "soundfile>=0.13.1",