Skip to content

FILE_ACCESS_GUIDE.md

Latest commit

 

History

History
325 lines (240 loc) · 7.14 KB

FILE_ACCESS_GUIDE.md

File metadata and controls

325 lines (240 loc) · 7.14 KB

File Access Guide - How the Sync Tool Gets Music Files

Overview

The sync tool copies files directly from the filesystem, not through Plex streaming.

┌─────────────┐       ┌──────────────┐       ┌─────────┐
│ Plex Server │──────▶│  Your Mac    │──────▶│  iPod   │
│             │ API   │              │ Copy  │         │
│  Metadata   │       │ File Access  │       │ Storage │
└─────────────┘       └──────────────┘       └─────────┘
     │                        │
     │                        │
     ▼                        ▼
 File Paths            Actual Files

Scenario 1: Plex on Your Mac

Setup:

Your Mac
├── Plex Server (running locally)
└── Music files at: /Users/jarren/Music/

How it works:

  1. Plex says: "Song is at /Users/jarren/Music/Artist/Song.mp3"
  2. Script accesses file directly (local filesystem)
  3. Copies to iPod ✅

Config needed:

# No path mapping needed!
path_mapping:
  server_path: ""
  local_path: ""

Scenario 2: Plex on LAN Server (Your Case!)

Setup:

Server (192.168.1.50)
├── Plex Server (running)
└── Music files at: /mnt/music/

Your Mac (192.168.1.100)
├── Connects to Plex via API
└── Needs to mount server's /mnt/music/

The Problem:

Plex reports: /mnt/music/Artist/Song.mp3
Your Mac thinks: "I don't have /mnt/music/!"
Result: ✗ File not found

The Solution - Mount & Map:

Step 1: Mount Server Music Directory

# Create mount point
mkdir -p ~/Music/ServerMusic

# Mount the server's music share
mount_smbfs //username@192.168.1.50/music ~/Music/ServerMusic

Now your Mac can access files at:

~/Music/ServerMusic/Artist/Song.mp3

Step 2: Configure Path Mapping

Edit config.yaml:

plex:
  url: "http://192.168.1.50:32400"
  # ... other settings ...

  path_mapping:
    server_path: "/mnt/music"                    # Server's path
    local_path: "/Users/jarren/Music/ServerMusic"  # Your Mac's mount

Step 3: How Translation Works

Plex reports:    /mnt/music/Artist/Album/Song.mp3
                     ↓ (path mapping)
Script translates:   /Users/jarren/Music/ServerMusic/Artist/Album/Song.mp3
                     ↓
Script accesses:     ~/Music/ServerMusic/Artist/Album/Song.mp3
                     ↓
Copies to iPod:      /Volumes/IPOD/Music/Artist/Album/Song.mp3

Finding Your Server Path

To find what path Plex uses:

Method 1: Plex Web Interface

  1. Open a song in Plex Web
  2. Click "..." → "Get Info"
  3. Look at the file path shown
  4. Example: /mnt/media/music/Artist/Song.mp3
  5. The prefix is: /mnt/media/music

Method 2: Plex Settings

  1. Go to Settings → Libraries → Music
  2. View the library folder path
  3. That's your server path

Method 3: Via API (Quick Test)

# Get a track's path
curl -X GET "http://YOUR_PLEX_IP:32400/library/sections/1/all?X-Plex-Token=YOUR_TOKEN" | grep -o '<Part.*file="[^"]*"' | head -1

# Look for the file="..." attribute
# Example output: file="/mnt/music/..."

Common Mount Methods

SMB (Windows/Samba shares)

# Interactive (prompts for password)
mount_smbfs //username@server-ip/music ~/Music/ServerMusic

# With credentials
mount_smbfs //username:password@server-ip/music ~/Music/ServerMusic

NFS (Linux servers)

# Mount NFS share
sudo mount -t nfs server-ip:/export/music ~/Music/ServerMusic

# Add to /etc/fstab for automatic mounting
server-ip:/export/music /Users/jarren/Music/ServerMusic nfs auto,noowners 0 0

AFP (Apple File Protocol)

mount_afp afp://username@server-ip/music ~/Music/ServerMusic

Finder Mount (GUI Method)

  1. Finder → Go → Connect to Server (⌘K)
  2. Enter: smb://server-ip/music
  3. Connect and authenticate
  4. Note where it mounts (usually /Volumes/music)
  5. Use that as local_path

Automatic Mounting

To mount automatically when syncing:

Option 1: Add to Sync Script

Create ~/sync-ipod-with-mount.sh:

#!/bin/bash

# Mount server music
echo "Mounting server music..."
if [ ! -d ~/Music/ServerMusic/Artist ]; then
    mkdir -p ~/Music/ServerMusic
    mount_smbfs //username@server-ip/music ~/Music/ServerMusic
fi

# Mount iPod
if [ ! -d /Volumes/IPOD ]; then
    diskutil mount /dev/disk4s2
fi

# Run sync
cd /Users/jarren/Nextcloud/Documents/Resources/Scripts/plex-ipod-playlist-sync
python3 plex_ipod_sync.py "$@"

# Cleanup
read -p "Unmount server and iPod? (y/n) " -n 1 -r
if [[ $REPLY =~ ^[Yy]$ ]]; then
    umount ~/Music/ServerMusic
    diskutil unmount /Volumes/IPOD
fi

Option 2: Auto-mount via /etc/fstab

For NFS shares, add to /etc/fstab:

server-ip:/export/music  /Users/jarren/Music/ServerMusic  nfs  auto,noowners  0  0

Then it mounts automatically at boot.

Troubleshooting

"File not found" errors

✗ File not found: /mnt/music/Artist/Song.mp3

Causes:

  1. Server mount not active
  2. Wrong path mapping
  3. File actually missing

Fix:

# Check if server is mounted
ls ~/Music/ServerMusic/

# If empty or error, remount
mount_smbfs //user@server/music ~/Music/ServerMusic

# Verify file exists
ls ~/Music/ServerMusic/Artist/Song.mp3

Path mapping not working

If files still not found after configuring mapping:

  1. Check exact paths:

    # What does Plex report?
# Run sync with --dry-run and look at error messages

# Does local path exist?
ls -la /Users/jarren/Music/ServerMusic/

  2. Test translation manually:

    # Test in Python
server = "/mnt/music/test.mp3"
local = server.replace("/mnt/music", "/Users/jarren/Music/ServerMusic", 1)
print(local)
# Should output: /Users/jarren/Music/ServerMusic/test.mp3

  3. Verify exact prefixes match:

    • Server path: /mnt/music ✓
    • Server path: /mnt/music/ ✗ (trailing slash)
    • Must match exactly!

Permission denied

Permission denied: /Users/jarren/Music/ServerMusic/...

Fix:

  • Check mount permissions
  • May need to mount with your user ID
  • For SMB: mount_smbfs -o nosuid,noowners ...

Complete Example Config

For a typical LAN server setup:

plex:
  url: "http://192.168.1.50:32400"
  use_token: true
  token: "abc123xyz"
  music_library: "Music"

  # Server reports paths like: /mnt/media/music/...
  # But files are mounted at: ~/Music/ServerMusic/...
  path_mapping:
    server_path: "/mnt/media/music"
    local_path: "/Users/jarren/Music/ServerMusic"

ipod:
  mount_point: "/Volumes/IPOD"
  music_dir: "/Volumes/IPOD/Music"
  playlist_dir: "/Volumes/IPOD/Playlists"

Quick Setup Checklist

  • Mount server music directory on Mac
  • Verify files are accessible: ls ~/Music/ServerMusic/
  • Find server path from Plex
  • Configure path mapping in config.yaml
  • Test with --dry-run first
  • Check for "File not found" errors
  • Adjust paths if needed
  • Run actual sync

Created: 2025-10-29 For: Plex to iPod Playlist Sync Tool