streamystats

Streamystats provides AI-driven features using embeddings and vector similarity:

Embeddings

Library items are embedded using OpenAI-compatible APIs (if enabled). These embeddings are stored in vectorchord, which supports any dimension and automatically creates optimized vector indexes for similarity search.

AI Chat

The interactive chat interface supports multiple providers via any OpenAI-compatible API. It utilizes function calling with 13 specialized tools, including:

• Personalized recommendations based on watch history.
• Semantic library search using embeddings.
• Watch statistics and most-watched content.
• Genre filtering and top-rated items.
• Recently added content discovery.

AI Recommendations

Recommendations are generated using cosine distance (vector similarity) to find content similar to your watch history. The system analyzes viewing patterns and provides explanations detailing which specific watched items triggered the suggestion.

For a production-ready Dockerless setup, use systemd to manage the three components: the database migration task, the job server, and the Next.js application.

1. Create a dedicated streamystats system user.
2. Set permissions for /opt/streamystats/{src,etc}.
3. Create and enable the following services:
   • streamystats-db-migration.service: Runs bun run db:migrate (Type: oneshot).
   • streamystats-job-server.service: Runs the job server (Type: simple).
   • streamystats-nextjs-app.service: Builds and starts the Next.js app (Type: simple).

Note: The job server service requires jellyfin.service to be present, and the Next.js app requires the job server to be running.

# 1. Setup user and permissions
useradd --system --home /opt/streamystats --create-home --shell /usr/sbin/nologin --user-group streamystats
chown -R streamystats:streamystats /opt/streamystats/{src,etc}

# 2. (After creating the .service files in /lib/systemd/system/)
systemctl daemon-reload
systemctl enable --now streamystats-db-migration.service
systemctl enable --now streamystats-job-server.service
systemctl enable --now streamystats-nextjs-app.service

Standard SQL Backup

Use pg_dump to create a portable SQL backup:

docker exec streamystats pg_dump -U postgres \
  --clean --if-exists --no-owner \
  streamystats > backup.sql

Flags:

• --clean: Adds DROP statements before CREATE (enables restore to existing DB).
• --if-exists: Adds IF EXISTS to DROP (prevents errors if objects don't exist).
• --no-owner: Omits ownership commands (makes the backup portable).

Restore:

cat backup.sql | docker exec -i streamystats psql -U postgres streamystats

Compressed Backup (Recommended)

For more efficient storage, use the custom format (-Fc):

docker exec streamystats pg_dump -U postgres \
  --clean --if-exists --no-owner -Fc \
  streamystats > backup.dump

Restore Compressed:

docker exec -i streamystats pg_restore -U postgres \
  --clean --if-exists -d streamystats < backup.dump

# Standard Backup
docker exec streamystats pg_dump -U postgres \
  --clean --if-exists --no-owner \
  streamystats > backup.sql

# Restore
cat backup.sql | docker exec -i streamystats psql -U postgres streamystats

All API endpoints require authentication. External clients (mobile apps, scripts, etc.) should use the MediaBrowser token format in the Authorization header.

MediaBrowser Token Format

Use the Authorization header with the following structure:

Authorization: MediaBrowser Token="<access-token>"

You can also include optional metadata for better tracking:

Authorization: MediaBrowser Client="MyApp", Device="iPhone", DeviceId="abc123", Version="1.0.0", Token="<access-token>"

Parameter Reference

Obtaining a Token

To get a token, authenticate against your Jellyfin server's /Users/AuthenticateByName endpoint:

curl -X POST "https://your-jellyfin-server/Users/AuthenticateByName" \
  -H "Content-Type: application/json" \
  -d '{"Username": "your-username", "Pw": "your-password"}'

The response will contain an AccessToken. Use this value in the Token parameter of your Streamystats requests.