`README.md`

153 lines
# Museum Art Animation Bot

Automated bot that fetches random public domain artwork from Rijksmuseum, animates it using Grok AI, and posts to X.com.

## Features

- Fetches high-quality public domain artwork from Rijksmuseum
- Works without API key (limited) or with free Rijksmuseum API key
- Attempts animation using Grok API (optional)
- Posts to X.com with artwork details and hashtags
- Automatic cleanup of old files
- Configurable posting schedule

## Setup

1. **Clone and install dependencies:**
```bash
npm install
```

2. **Configure API credentials:**
```bash
cp .env.example .env
```

Edit `.env` file with your credentials:
- **X.com (Twitter) API**: Required for posting
- **Grok API**: Optional for animation (falls back to static images)
- **Rijksmuseum API**: Optional (works without but with rate limits)

3. **Run setup script:**
```bash
chmod +x setup.sh
./setup.sh
```

## Usage

### Run once:
```bash
npm run fetch  # Just fetch artwork
npm run post   # Post existing artwork
npm start      # Full process
node src/index.js --once  # Single run
```

### Schedule automatic posting:

**Option 1: Built-in scheduler (recommended for testing)**
```bash
node src/index.js
```

**Option 2: System cron (recommended for production)**
```bash
# Add to crontab (runs every 6 hours)
crontab -e
0 */6 * * * cd /root/animatemuseumposts && node src/index.js --once >> logs/cron.log 2>&1
```

**Option 3: Systemd service (most robust)**
```bash
sudo cp museum-art-bot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable museum-art-bot
sudo systemctl start museum-art-bot
```

## Configuration

### Environment Variables (.env):
- `TWITTER_API_KEY`: X.com API key
- `TWITTER_API_SECRET`: X.com API secret
- `TWITTER_ACCESS_TOKEN`: X.com access token
- `TWITTER_ACCESS_SECRET`: X.com access secret
- `GROK_API_KEY`: Grok API key (optional)
- `RIJKSMUSEUM_API_KEY`: Rijksmuseum API key (optional)
- `CRON_SCHEDULE`: Custom cron schedule (default: "0 */6 * * *")

### Posting Schedule:
Default is every 6 hours. Modify in:
- `.env` file: `CRON_SCHEDULE="0 */6 * * *"`
- Or in crontab directly

## API Information

### Rijksmuseum API
- No API key required for basic usage
- Register for free key at: https://data.rijksmuseum.nl/object-metadata/api/
- Focuses on public domain artwork from famous artists

### X.com (Twitter) API
- Required for posting
- Apply at: https://developer.twitter.com/
- Needs Elevated access for media upload

### Grok API
- Optional for AI animation
- Get access at: https://x.ai/api
- Falls back to static images if unavailable

## File Structure
```
animatemuseumposts/
├── src/
│   ├── index.js           # Main orchestrator
│   ├── fetchArtwork.js    # Rijksmuseum fetcher
│   ├── animateWithGrok.js # Animation processor
│   └── postToX.js         # X.com poster
├── output/                # Temporary artwork files
├── logs/                  # Application logs
├── .env                   # API credentials
└── package.json          # Dependencies
```

## Monitoring

Check logs:
```bash
tail -f logs/posts.log    # Successful posts
tail -f logs/errors.log   # Errors
tail -f logs/cron.log     # Cron output
```

Check systemd service:
```bash
sudo systemctl status museum-art-bot
sudo journalctl -u museum-art-bot -f
```

## Troubleshooting

1. **X.com authentication fails:**
   - Verify API credentials in .env
   - Ensure app has write permissions
   - Check rate limits

2. **No artwork found:**
   - Rijksmuseum API may be rate limited
   - Try adding API key for higher limits

3. **Animation fails:**
   - Grok API key may be invalid
   - Bot falls back to static images automatically

4. **Cron not running:**
   - Check cron service: `sudo service cron status`
   - Verify paths are absolute in crontab
   - Check logs directory permissions

## License

MIT