File Organization

How GDrive Ingest automatically organizes files by type, with smart music categorization by artist, album, and year

Overview

GDrive Ingest automatically categorizes and organizes files based on their type and metadata. Music files get special treatment with artist/album/year folder structures and embedded cover art extraction.

File Categories

Files are automatically sorted into these categories:

Music

Extensions: .mp3, .flac, .m4a, .wav, .aac, .ogg, .opus, .wma

Organization:

Music/
└── Artist Name/
    └── Album Title (Year)/
        ├── 01 - Track.mp3
        ├── 02 - Track.mp3
        └── cover.jpg

See Music Files for details.

Videos

Extensions: .mp4, .mkv, .avi, .mov, .wmv, .flv, .webm, .m4v

Organization:

Videos/
├── movie1.mp4
├── movie2.mkv
└── clip.avi

Images

Extensions: .jpg, .jpeg, .png, .gif, .webp, .svg, .bmp, .ico

Organization:

Images/
├── photo1.jpg
├── screenshot.png
└── graphic.svg

Documents

Extensions: .pdf, .txt, .doc, .docx, .xls, .xlsx, .ppt, .pptx

Organization:

Docs/
├── report.pdf
├── notes.txt
└── spreadsheet.xlsx

Archives

Extensions: .zip (when extracted)

Organization:

Folders/
└── archive-name/
    ├── file1.txt
    ├── file2.jpg
    └── subdir/
        └── file3.pdf

Others

Everything else: Any file type not matching above categories

Organization:

Others/
├── data.csv
├── config.yaml
└── unknown.xyz

Music Files

Smart Metadata Extraction

Music files are analyzed with ffprobe to extract ID3 tags:

ffprobe -v quiet -show_entries format_tags=artist,album,title,date file.mp3

Extracted metadata:

• Artist: Track artist name
• Album: Album title
• Title: Song title
• Year: Release year (from date tag)

Folder Structure

1. Artist folder

   Created in Music/ directory:

   Music/
   └── Don Toliver/
   
2. Album folder

   Created inside artist folder with year:

   Music/
   └── Don Toliver/
       └── Tiramisu (2025)/
   

   If no year in metadata:

   Music/
   └── Don Toliver/
       └── Tiramisu/
   
3. Track files

   Uploaded to album folder:

   Music/
   └── Don Toliver/
       └── Tiramisu (2025)/
           ├── 01 - Tiramisu.mp3
           ├── 02 - Another Track.mp3
           └── cover.jpg
   

Cover Art Extraction

Cover art is automatically extracted from embedded album art:

ffmpeg -y -i audio_file.mp3 -an -vcodec copy cover.jpg

Features:

• Extracted from first track in album
• Saved as cover.jpg
• Only extracted once per album
• Uploaded alongside music files

Example output:

💿 Don Toliver - Tiramisu (2025) - Tiramisu
   ⬆  Uploading 8.52MB... ✓ Uploaded 8.52MB
   🖼  Cover art... ✓ Cover art uploaded

Metadata Cleaning

Metadata is cleaned to remove website spam:

# Before
Artist: "Don Toliver (HipHopKit.com)"
Album: "Tiramisu | Audiomack.com"

# After
Artist: "Don Toliver"
Album: "Tiramisu"

Cleaned patterns:

• Website names: HipHopKit.com, Audiomack.com
• Platforms: SoundCloud, Spotify, YouTube
• Generic domains: [domain].(com|net|org)
• Parentheses and pipes around spam

Implementation (from script line 711-713):

artist=$(echo "$artist" | sed -E 's/\s*[\(\|]?\s*(HipHopKit\.com|Audiomack\.com|SoundCloud|Spotify|YouTube|[A-Za-z0-9]+\.(com|net|org))[^\)]*[\)]?//gi' | sed 's/[[:space:]]*$//')

Handling Existing Albums

When uploading to an album folder that already exists:

1. Detection

   Script checks if album folder already exists:

   Checking for existing album: Tiramisu (2025)...
   ⚠ Album folder "Tiramisu (2025)" already exists
   
2. Prompt

   User is asked:

   Upload to existing folder? [Y/n]: 
   
3. Options

   Press Y or Enter (default):

   → Using existing album folder
   

   Uploads to existing album (adds more tracks).

   Press N:

   → Uploading to Music root (un-nested)
   

   Uploads directly to Music/Artist/ without album folder.

No Metadata Files

For music files without metadata:

Metadata: Unknown Artist|Unknown Album|Unknown Title|

Result:

Music/
└── Unknown Artist/
    └── song.mp3  (no album folder, no cover)

Or if artist exists but album is missing:

Music/
└── Artist Name/
    └── song.mp3  (no album folder)

ZIP Files

Extraction Workflow

When a ZIP file is detected:

1. Detection

   📦 ZIP detected
   Extract and upload files? (y/n): 
   
2. User choice

   Option 1: Extract (y)

   Extracting...
   ✓ Extracted
   

   Files are extracted and organized by type.

   Option 2: Upload as-is (n)

   Uploading ZIP file as-is
   

   ZIP uploaded to Others/ category.

Extracted ZIP Organization

Extracted files go to Folders/ category:

Folders/
└── archive-name/
    ├── document.pdf
    ├── image.jpg
    ├── song.mp3
    └── subdir/
        └── file.txt

Exception: If ZIP contains only music files, they’re organized by artist/album:

# Input: album.zip containing 10 .mp3 files
# Output:
Music/
└── Artist Name/
    └── Album Title (2025)/
        ├── 01 - Track.mp3
        ├── 02 - Track.mp3
        ├── ...
        └── cover.jpg

Mixed Content ZIP

ZIP with multiple file types:

# Input: mixed.zip containing:
# - music.mp3
# - photo.jpg
# - doc.pdf

# Output:
Folders/
└── mixed/
    ├── music.mp3
    ├── photo.jpg
    └── doc.pdf

Mixed content ZIPs preserve their structure in Folders/ category. Music files inside are NOT organized by artist/album.

Duplicate Detection

Files are checked for duplicates before upload:

1. MD5 checksum

   MD5=$(md5sum "$file" | awk '{print $1}')
   🔐 MD5: 6d2300f6a025e07ad87991b31023da6a
   
2. API query

   Check if file with same name exists in destination folder:

   query="name='filename.mp3' and 'folder_id' in parents and trashed=false"
   
3. Skip if exists

   ⛘ Already exists, skipping
   

   File is not re-uploaded.

Benefits:

• Prevents duplicate uploads
• Saves bandwidth
• Saves storage quota
• Speeds up batch processing

Temporary Files

Download Stage

File/Directory	Purpose	Cleanup
/tmp/<filename>_$$	Downloaded file	After upload
/tmp/tg_download_$$/	Telegram staging	After upload
/tmp/tg_output_$$	Telegram logs	After upload

Extraction Stage

File/Directory	Purpose	Cleanup
/tmp/extract_$$/	ZIP extraction	After upload
/tmp/single_$$/	Single file staging	After upload

Music Processing

File/Directory	Purpose	Cleanup
/tmp/covers_$$/	Extracted cover art	After upload

Upload Stage

File/Directory	Purpose	Cleanup
/tmp/upload_result_$$	API response	After processing
/tmp/cover_result_$$	Cover upload response	After processing

Auto cleanup:

Script automatically cleans up after each URL:

rm -rf "$TEMP_FILE" "$EXTRACT_DIR" "$FILES_DIR" /tmp/covers_$$ 2>/dev/null

Manual cleanup:

If script crashes:

./cleanup_temp.sh

See dedicated guide: Troubleshooting - Temp Files

Persistent Files

Telegram Session

~/.config/gdrive-ingest/telegram/downloader.session

Purpose: Telegram authentication
Size: ~1-2 KB
Cleanup: Only delete to re-authenticate

Google Drive Token Cache

~/.gdrive_token

Purpose: Cached access token
Size: Less than 1 KB
Cleanup: Auto-refreshed when expired

Organization Examples

Single Song Upload

./gdrive_ingest.sh https://example.com/song.mp3

Result:

Music/
└── Don Toliver/
    └── Tiramisu (2025)/
        ├── Tiramisu.mp3
        └── cover.jpg

Album Upload

./gdrive_ingest.sh track1.mp3 track2.mp3 track3.mp3

Result:

Music/
└── Artist Name/
    └── Album Title (2025)/
        ├── 01 - Track.mp3
        ├── 02 - Track.mp3
        ├── 03 - Track.mp3
        └── cover.jpg  (extracted once)

Multiple Artists

./gdrive_ingest.sh artist1.mp3 artist2.mp3 artist3.mp3

Result:

Music/
├── Artist 1/
│   └── Album (2025)/
│       └── song.mp3
├── Artist 2/
│   └── Album (2024)/
│       └── song.mp3
└── Artist 3/
    └── Album (2023)/
        └── song.mp3

Mixed File Types

./gdrive_ingest.sh song.mp3 video.mp4 photo.jpg doc.pdf

Result:

Music/
└── Artist/
    └── Album/
        └── song.mp3

Videos/
└── video.mp4

Images/
└── photo.jpg

Docs/
└── doc.pdf

Customization

Override Folder

Force all files to a specific folder:

./gdrive_ingest.sh --folder "My Folder" song.mp3 video.mp4

Result:

My Folder/
├── song.mp3  (not organized by artist)
└── video.mp4

Using --folder overrides automatic categorization. Files upload directly to specified folder.

Create Folders On-The-Fly

In interactive mode:

1. Select ”● Create new folder”
2. Enter folder name: Archive 2025
3. Files upload to new folder

Next Steps

Usage Examples

See real-world organization examples

Interactive Features

Master folder navigation

Troubleshooting

Fix organization issues

Setup Guide

Configure the script