File Organization - TheTeleporter Scripts

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:

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

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

See Music Files for details.

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

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

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

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

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

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

Extensions: .zip (when extracted)Organization:

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

Everything else: Any file type not matching above categoriesOrganization:

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

Artist folder

Created in Music/ directory:

Music/
└── Don Toliver/

Album folder

Created inside artist folder with year:

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

If no year in metadata:

Music/
└── Don Toliver/
    └── Tiramisu/

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:

Detection

Script checks if album folder already exists:

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

Prompt

User is asked:

Upload to existing folder? [Y/n]:

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:

Detection

📦 ZIP detected
Extract and upload files? (y/n): 

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:

MD5 checksum

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

API query

Check if file with same name exists in destination folder:

query="name='filename.mp3' and 'folder_id' in parents and trashed=false"

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:

Select ”● Create new folder”
Enter folder name: Archive 2025
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

Get Started

Scripts

GDrive Ingest

Development

Documentation Index

​Overview

​File Categories

​Music Files

​Smart Metadata Extraction

​Folder Structure

​Cover Art Extraction

​Metadata Cleaning

​Handling Existing Albums

​No Metadata Files

​ZIP Files

​Extraction Workflow

​Extracted ZIP Organization

​Mixed Content ZIP

​Duplicate Detection

​Temporary Files

​Download Stage

​Extraction Stage

​Music Processing

​Upload Stage

​Persistent Files

​Telegram Session

​Google Drive Token Cache

​Organization Examples

​Single Song Upload

​Album Upload

​Multiple Artists

​Mixed File Types

​Customization

​Override Folder

​Create Folders On-The-Fly

​Next Steps

Usage Examples

Interactive Features

Troubleshooting

Setup Guide

Build docs developers (and LLMs) love

Overview

File Categories

Music Files

Smart Metadata Extraction

Folder Structure

Cover Art Extraction

Metadata Cleaning

Handling Existing Albums

No Metadata Files

ZIP Files

Extraction Workflow

Extracted ZIP Organization

Mixed Content ZIP

Duplicate Detection

Temporary Files

Download Stage

Extraction Stage

Music Processing

Upload Stage

Persistent Files

Telegram Session

Google Drive Token Cache

Organization Examples

Single Song Upload

Album Upload

Multiple Artists

Mixed File Types

Customization

Override Folder

Create Folders On-The-Fly

Next Steps