Jinshu (锦书) v1.1.0 📺

Let distant love arrive instantly ❤️

A minimalist cross-space photo and video casting system. Remotely send media from mobile browsers to seniors' TV screens with zero interaction required on their end.

简体中文 | English

Young people living in different cities often long to share daily moments—children's growth, weekend trips, warm family videos—with their parents and seniors back home.

However, traditional smart devices and sharing methods face two major obstacles:

1. Senior's Tech Barrier: Seniors living alone back home are often unfamiliar with complex smart devices or computer software. Even simple actions like clicking to receive or opening a file can be an invisible barrier.
2. Screen Limitations: Mobile screens are too small and the experience is fragmented. Watching is strenuous for seniors with deteriorating vision, and it lacks the "family album ritual" of large displays.

Jinshu (锦书) is born to solve this pain point. The system adopts a thoughtful design of "TV connected to a PC (like a micro PC) for display, and distant children using mobile devices to cast remotely". Back home, simply run the Jinshu agent silently in the background of the computer connected to the TV:

• 👴 Zero-Interaction for Seniors: Elders do not need to master any computer or remote control operations. Once children send new photos or videos, the system automatically wakes up the screen, kills the screen saver, and brings the gallery page to full screen.
• 👩‍👧‍👦 Minimalist Sending for Children: Family members only need to open the web page on their phones, select photos/videos, and click send. Love and warmth reach the TV screen instantly across thousands of miles.

• 📱 Minimalist Web Upload: Supports all major mobile devices (iOS/Android/HarmonyOS). No app download needed; simply add the web page to your home screen for a native-like experience.
• 📺 Zero-Interaction Client: Automatically wakes up the screen, silently kills screen savers, and launches a full-screen, pinned gallery browser. Fully hands-free for seniors.
• 📸 Adaptive Image Compression: High-res images are automatically processed by an adaptive 2K resolution algorithm on the server, compressing the size by 90% while maintaining high fidelity, boosting load times by 10-20x.
• ⚡ Seamless HEIC Conversion: Native support for iPhone's HEIC/HEIF image formats, automatically converting them to lossless JPG on the server.
• 🎬 Mixed Media Slideshow: Supports auto-rotation of both photos and videos (photos display for 10 seconds, videos play with audio muted and switch automatically upon completion).
• 🔗 Smart 4-Digit Pairing: Uses typical TV-pairing logic with a 5-minute timeout. Device association is encrypted and cleared instantly after success. One device can be paired with multiple family members.
• 🔒 Security & Single Instance Lock: Encrypted via HTTPS/WSS. Single-instance lock on the agent prevents duplicate background running.
• 🐳 Modern Architecture: FastAPI + Tortoise-ORM backend for high concurrency, lightweight and fast; lightweight Tkinter GUI + system tray client.

┌─────────────────┐         ┌────────────────┐         ┌─────────────────┐
│   Mobile Web    │  HTTPS  │  Cloud Server  │   WSS   │  Windows Client │
│ (Family Member) │ ───────>│   (FastAPI)    │<────────│  (Senior's TV)  │
│                 │         │                │         │                 │
│ - Login Auth    │         │ - Device Pair  │         │ - Tray Mode     │
│ - Select Device │         │ - Image Compr  │         │ - Wake Screen   │
│ - Easy Cast     │         │ - Format Adapt │         │ - Kill ScrSaver │
│ - Progress Bar  │         │ - Msg Dispatch │         │ - Fullscr Play  │
└─────────────────┘         └────────────────┘         └─────────────────┘
                                    │
                                    │ SQLite
                                    ▼
                            ┌────────────────┐
                            │    Database    │
                            │ - Users/Devices│
                            │ - Session/Logs │
                            └────────────────┘

The project consists of two parts: server (Cloud Server) and agent (Windows Client).

Ubuntu 20.04+ is recommended.

1. Clone the code and enter the directory:

   git clone https://github.com/yourusername/jinshu.git
   cd jinshu/server

2. Run the deployment script (automatically installs dependencies, configures virtual environment, systemd services, and Nginx):

   chmod +x deploy.sh
   sudo ./deploy.sh

3. Configure .env and start: Copy server/.env.example to server/.env, fill in your actual BASE_URL and admin password, then start the service:

   sudo systemctl start jinshu
   sudo systemctl enable jinshu

   📌 Custom Domains & SSL Certificates Guide: Please refer to the One-stop Deployment Guide (docs/DEPLOY_GUIDE.md).

On the Windows 10/11 computer connected to the TV back home:

1. Run the program: Run the packaged 锦书接收端.exe, or run from source code:

   cd agent
   pip install -r requirements.txt
   python agent.py

2. Configure the Server URL: The client generates a config file at %APPDATA%\Jinshu\config.json on its first run. Open it and modify "server_url" to point to your WebSocket domain:

   {
       "server_url": "wss://jins.yourdomain.com/ws/device"
   }

3. Set auto-start on boot (highly recommended): Press Win + R, enter shell:startup, and drag a shortcut of 锦书接收端.exe into this folder.

   📌 PyInstaller Packaging Guide: Please refer to the Deployment Guide (docs/DEPLOY_GUIDE.md#第三部分windows-客户端打包与分发-agent).

1. Open a mobile browser, visit https://jins.yourdomain.com, and log in with your admin credentials.
2. Note the 4-digit pairing code shown on the TV screen.
3. Click "Bind new device" on the phone, enter the pairing code, name it (e.g., "Home TV"), and confirm to bind!

   📌 User Manual & FAQ: Please refer to the User Guide (docs/USER_GUIDE.md).

jinshu/
├── server/                 # Server-side directory (deployed on cloud server)
│   ├── main.py            # FastAPI main application
│   ├── init_db.py         # DB initialization script
│   ├── deploy.sh          # One-click deployment script
│   └── nginx.conf         # Nginx proxy config template
│
├── agent/                 # Client-side directory (runs on TV client PC)
│   ├── agent.py           # GUI & Websocket receiver
│   ├── agent.spec         # PyInstaller spec file
│   └── build.bat          # Windows one-click packaging batch script
│
├── docs/                  # 📖 Core Documentations
│   ├── DEPLOY_GUIDE.md    # One-stop Deployment & Packaging Guide
│   └── USER_GUIDE.md      # User Manual & FAQ (Chinese)
│
├── README-CN.md           # Chinese README
└── README.md              # English README (this file)

This project is licensed under the MIT License. It is intended for personal study and family companionship only. Let technology bring loved ones closer.