Skip to content

advanced-guide.en.md

Latest commit

 

History

History
275 lines (218 loc) · 7.99 KB

advanced-guide.en.md

File metadata and controls

275 lines (218 loc) · 7.99 KB
Raw

📘 Advanced Usage Guide

Table of Contents

Zero-Intrusion Design

Folder2Podcast RSS implements a zero-intrusion design pattern, which means:

Data Safety

  • 🔒 Read-Only Access - Application only requires read permission for audio folders
  • 📁 Original File Protection - Never modifies any original audio files or folder structure
  • 🔄 State Isolation - All generated files (e.g., feed.xml) are stored in a separate .feeds directory

Technical Implementation

  • 🛡️ Permission Isolation - Uses separate storage space for application state management
  • 📊 Cache Optimization - Optimized feed file generation and caching strategy
  • 🔍 Smart Monitoring - Efficient detection of filesystem changes

Best Practices

  • Mount audio folders in read-only mode
  • Regularly clean cache files in the .feeds directory
  • Monitor system resource usage

File Naming Convention

Smart Filename Processing

The system supports two filename formats and processes them intelligently:

1. Numbered Format (Recommended)

  • Format 1: Number + Title.extension (e.g., 01-Chapter1.mp3)
  • Format 2: Title + Number.extension (e.g., Chapter01.mp3)
  • System prioritizes numbers at the start of filenames for episode numbering

2. Non-numbered Format

  • Use descriptive filenames (e.g., Introduction.mp3)
  • System generates unique sorting values based on creation time and file size
  • Preserves complete filename as title (without extension)

Title Display Strategy

Control title display through global environment variables or per-podcast configuration:

  • Full Mode (Default): Preserves original filename (without extension)

    01-Intro.mp3    → "01-Intro"
Episode01.mp3   → "Episode01"
Intro01.mp3     → "Intro01"

  • Clean Mode: Removes numbers and separators (only for numbered files)

    01-Intro.mp3    → "Intro"
Episode01.mp3   → "Episode"
Intro01.mp3     → "Intro"

Configuration Details

Complete podcast.json Configuration

{
  "title": "Podcast Title",
  "description": "Podcast Description",
  "author": "Author Name",
  "email": "author@example.com",
  "language": "en-us",
  "category": "Technology",
  "explicit": false,
  "websiteUrl": "https://example.com",
  "titleFormat": "clean",
  "coverSearchTerm": "search term for fetching cover (optional)",
  "coverImageUrl": "direct image URL for cover (optional, highest priority)"
}

Configuration Item Details

  • title: The podcast title
  • description: Podcast description
  • author: Author name
  • email: Contact email
  • language: Language code (RFC 5646)
  • category: Podcast category
  • explicit: Content rating flag
  • websiteUrl: Related website
  • titleFormat: Title format, supports 'clean' (cleaned title) or 'full' (complete filename)

Episode Number Extraction Strategy

The system supports multiple strategies for extracting episode numbers from filenames:

Default Strategies

  1. Prefix Matching (Primary)

    • Finds numbers at the start of filename
    • Example: 001-TechDaily.mp3 → Number: 1
    • Example: 123_AI-History.mp3 → Number: 123

  2. Suffix Matching (Secondary)

    • Finds numbers before file extension
    • Example: TechDaily_001.mp3 → Number: 1
    • Example: AI-History-123.mp3 → Number: 123

Configurable Strategies

You can configure the following strategies in podcast.json:

  1. First Number

    {
  "episodeNumberStrategy": "first"
}
    • Scans left to right, uses the first number found
    • Example: ep01TechNews08.mp3 → Number: 1

  2. Last Number

    {
  "episodeNumberStrategy": "last"
}
    • Scans right to left, uses the last number found
    • Example: ep01TechNews08.mp3 → Number: 8

  3. Custom Regular Expression

    {
  "episodeNumberStrategy": {
    "pattern": "ep(\\d+)"
  }
}
    • Uses custom regex pattern for precise matching
    • Example: ep01TechNews.mp3 → Number: 1

📝 Note:

  • Uses prefix matching by default when not configured
  • Custom regex must include one capture group ()
  • Falls back to default strategy if extraction fails

Episode Time Management

The system provides two time management strategies, controlled by the useMTime configuration in podcast.json:

  1. Default Strategy (useMTime: false):

    • For Numbered Files:
      • Uses base date (2024-12-18) plus episode number to generate publish time
      • Lower numbers get earlier publish dates
      • Example: 01-Intro.mp3 publishes before 02-Main.mp3
    • For Non-numbered Files:
      • Uses actual file creation time as publish date
      • Generates unique sorting value from creation time and file size
      • Maintains natural time order

  2. File Time Strategy (useMTime: true):

    • Always uses file creation time as publish date
    • Applies to all files (regardless of numbering)
    • Completely based on filesystem timestamps
    • Configuration example: 
      {
  "title": "My Podcast",
  "description": "Podcast Description",
  "useMTime": true
}

📝 Tips:

  • Use useMTime: true if you want to rely entirely on file creation times for publish order
  • Use default setting or useMTime: false if you want to control publish order through filename numbers
  • This configuration can be set individually for each podcast, allowing different strategies for different podcasts

URL Access Standards

The system provides standard URL access methods:

Audio file access:

http://[server-address]/audio/[podcast-folder-name]/[audio-filename]

RSS Feed access:

http://[server-address]/feeds/[podcast-folder-name].xml

📝 Note:

  • Podcast folder name is your audio directory name
  • Ensure folder names don't contain special characters
  • All non-ASCII characters in URLs will be automatically encoded

Deployment Methods

NPM Deployment

  1. Requirements

    • Node.js 14.0 or higher
    • NPM 6.0 or higher
    • Prepared audio directory

  2. Installation

    # Clone repository
git clone https://github.com/your-repo/folder2podcast.git
cd folder2podcast

# Install dependencies
npm install

# Configure environment variables (optional)
export AUDIO_DIR=/path/to/audiobooks
export PORT=3000

  3. Start Service

    # Development mode
npm run start:dev

# Or start with specific config
AUDIO_DIR=/path/to/audiobooks PORT=3000 npm run start:dev

  4. Verify Service

    • Access dashboard: http://localhost:3000/podcasts
    • Verify audio files are accessible
    • Test podcast subscription functionality

API Usage

1. Podcast List API

  • Access /podcasts to get all available podcasts
  • Returns detailed information including title, description, subscription URLs
  • Feed URLs include complete access addresses ready for subscription

2. Resource Access

  • Podcast cover: /audio/podcast-name/cover.jpg
  • Audio files: /audio/podcast-name/episode.mp3
  • Default resources: /image/default-cover.jpg

Static Resource Directory Structure

assets/
├── web/          # Web interface files
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── image/        # Image resources
│   └── default-cover.jpg

Best Practices

1. Directory Organization

  • Separate folder for each podcast series
  • Use number prefixes for correct ordering
  • Add clear file descriptions
  • Configure appropriate podcast information

2. Performance Optimization

  • Control number of files per folder
  • Add appropriately sized cover images (square recommended)
  • Optimize audio file formats for streaming

3. Security

  • Use read-only mounts to protect audio files
  • Avoid special characters in filenames