Output Formats

Record Shelf supports multiple output formats to suit different use cases. Each format has its own advantages and is optimized for specific scenarios.

Format Overview

Format Comparison
Format	Extension	Best For	Features	File Size
Excel	`.xlsx`	Analysis, Sharing	Multiple sheets, Formatting	Medium
CSV	`.csv`	Data Import, Processing	Universal compatibility	Small
HTML	`.html`	Web viewing, Presentation	Browser compatible	Medium

Excel Format (.xlsx)

The Excel format is the default and most feature-rich output option.

Features

Multiple Worksheets:

“Collection” sheet: Contains all items from all shelves
Individual shelf sheets: Separate sheet for each shelf
Professional formatting: Headers, borders, and styling

Data Organization:

Sortable columns
Freeze panes for easy navigation
Auto-sized columns
Consistent formatting

Excel Compatibility:

Works with Microsoft Excel 2010+
Compatible with LibreOffice Calc
Google Sheets compatible
Numbers (Mac) compatible

Usage

# Default Excel output
record-shelf generate --username myuser

# Custom Excel filename
record-shelf generate --username myuser --output my_collection.xlsx

# Excel is the default format
record-shelf generate --username myuser --format xlsx

Worksheet Structure

Collection Sheet:

Contains all items from all shelves
Sorted by shelf, then artist, then title
Includes all data columns

Individual Shelf Sheets:

One sheet per shelf (e.g., “Vinyl”, “CD”, “Digital”)
Contains only items from that specific shelf
Same column structure as main sheet
Sheet names are truncated to 31 characters (Excel limit)

Best Practices

Use for detailed analysis and reporting
Great for sharing with non-technical users
Ideal for presentations and documentation
Perfect for Excel-based workflows

CSV Format (.csv)

The CSV format provides universal compatibility and is ideal for data processing.

Features

Universal Compatibility:

Opens in any spreadsheet application
Compatible with databases
Scriptable and automatable
Human-readable text format

Data Processing:

Easy to import into databases
Works with data analysis tools
Compatible with pandas, R, etc.
Small file size

Simplicity:

Single file with all data
No formatting overhead
Fast generation and loading
Version control friendly

Usage

# CSV output
record-shelf generate --username myuser --format csv --output collection.csv

# CSV with custom filename
record-shelf generate --username myuser --format csv --output my_data.csv

Data Structure

Single File:

All collection data in one file
Header row with column names
One row per collection item
Comma-separated values

Column Order:

shelf
artist
title
label
catalog_number
format
year
genre
style
country
discogs_id
master_id
rating
notes

Example CSV Output:

shelf,artist,title,label,catalog_number,format,year,genre,style,country,discogs_id,master_id,rating,notes
Vinyl,"The Beatles","Abbey Road",Apple,PCS 7088,"Vinyl, LP, Album",1969,Rock,"Pop Rock",UK,123456,78910,,
CD,"Pink Floyd","Dark Side of the Moon","Harvest",CDP 7 46001 2,"CD, Album",1990,Rock,"Progressive Rock",UK,234567,89012,,

Best Practices

Use for data analysis and processing
Ideal for importing into databases
Perfect for automation scripts
Great for version control systems
Choose when file size matters

HTML Format (.html)

The HTML format creates web-viewable reports that can be shared easily.

Features

Web Compatibility:

Opens in any web browser
No additional software required
Mobile-friendly responsive design
Professional table styling

Presentation:

Clean, readable layout
Sortable columns (with JavaScript)
Professional appearance
Print-friendly styling

Sharing:

Easy to email or host online
Self-contained file
Works offline
Cross-platform compatible

Usage

# HTML output
record-shelf generate --username myuser --format html --output collection.html

# HTML with custom filename
record-shelf generate --username myuser --format html --output my_collection.html

HTML Structure

Document Structure:

HTML5 compliant
Embedded CSS styling
Responsive table layout
Professional typography

Table Features:

Header row with column names
Alternating row colors
Hover effects
Responsive breakpoints

Styling:

Clean, modern design
Professional color scheme
Mobile-responsive layout
Print optimization

Example HTML Output:

<!DOCTYPE html>
<html>
<head>
    <title>Record Collection</title>
    <style>
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
        th { background-color: #f2f2f2; }
        tr:nth-child(even) { background-color: #f9f9f9; }
    </style>
</head>
<body>
    <h1>Music Collection Report</h1>
    <table>
        <thead>
            <tr><th>Shelf</th><th>Artist</th><th>Title</th>...</tr>
        </thead>
        <tbody>
            <tr><td>Vinyl</td><td>The Beatles</td><td>Abbey Road</td>...</tr>
        </tbody>
    </table>
</body>
</html>

Best Practices

Use for quick viewing and sharing
Ideal for presentations
Great for non-technical users
Perfect for web-based workflows
Choose for visual appeal

Choosing the Right Format

Decision Matrix

Choose Excel (.xlsx) when:

You need multiple worksheets
Working with Excel-based workflows
Sharing with business users
Need professional formatting
Want sortable, filterable data

Choose CSV (.csv) when:

Importing into databases
Using data analysis tools
Automating data processing
File size is important
Need version control compatibility

Choose HTML (.html) when:

Quick viewing in browsers
Sharing via email or web
Need mobile compatibility
Want professional presentation
No special software requirements

Performance Considerations

Performance Comparison
Format	Generation Speed	File Size	Memory Usage	Loading Speed
Excel	Slow	Large	High	Medium
CSV	Fast	Small	Low	Fast
HTML	Medium	Medium	Medium	Fast

Multiple Format Generation

You can generate multiple formats from the same data:

# Generate all formats
record-shelf generate --username myuser --output collection.xlsx --format xlsx
record-shelf generate --username myuser --output collection.csv --format csv
record-shelf generate --username myuser --output collection.html --format html

Automation Script Example:

#!/bin/bash
export DISCOGS_TOKEN="your_token"
USERNAME="your_username"
DATE=$(date +%Y%m%d)

# Generate all formats with date
record-shelf generate --username $USERNAME --output "${DATE}_collection.xlsx" --format xlsx
record-shelf generate --username $USERNAME --output "${DATE}_collection.csv" --format csv
record-shelf generate --username $USERNAME --output "${DATE}_collection.html" --format html

Customization Options

File Naming

Use descriptive filenames
Include dates for archival
Use consistent naming schemes
Consider automated naming

Examples:

# Date-based naming
--output "collection_$(date +%Y%m%d).xlsx"

# Shelf-specific naming
--output "vinyl_collection.xlsx" --shelf "Vinyl"

# User-specific naming
--output "${USERNAME}_complete.csv"

Output Directory

Organize outputs in directories:

# Create output directory
mkdir -p reports/$(date +%Y%m)

# Generate to specific directory
record-shelf generate --username myuser --output "reports/$(date +%Y%m)/collection.xlsx"

Troubleshooting Output Issues

Common Problems

File Permission Errors:

Error: Permission denied

Solutions:
- Check write permissions on output directory
- Ensure file isn't open in another application
- Try different output location

Corrupt Files:

Error: File cannot be opened

Solutions:
- Check available disk space
- Ensure process completed successfully
- Try different output format

Large File Issues:

Warning: Large collection detected

Solutions:
- Use CSV format for better performance
- Filter by shelf to reduce size
- Increase available memory

Validation

Validate your output files:

# Check file was created
ls -la collection.xlsx

# Check file size (should be > 0)
du -h collection.xlsx

# Quick content check for CSV
head -5 collection.csv