nex_buddy/server/app/services/media.py

283 lines
9.8 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""媒体服务:落盘、图片自动处理、设备清单与同步状态。
图片「自动处理」的边界(服务端一次做足,设备端零处理):
- 任何能解码的格式(jpg/png/webp/gif 首帧/bmp)统一转 JPEG;
- 最长边压到 720px(360 圆屏 ×2 余量,相册放大不糊);
- EXIF/旋转信息直接烧进像素(ImageOps.exif_transpose),设备端不用懂方向;
- 质量按内容定:先试 85,大于 1.5MB 再降到 70 —— 圆屏上看不出差别,
但 TF 卡和同步流量都省一半以上。
音乐不做任何处理:MP3 原样透传,解码在副控。但会抽取 ID3v2 里内嵌的
专辑封面(APIC),压成 480px JPEG 存到 covers/,网页列表当缩略图用;
设备端唱片机本来就自己解内嵌封面,不走这份。
"""
from __future__ import annotations
import io
import uuid
import zlib
from pathlib import Path
from fastapi import HTTPException
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.config import settings
from app.models import Device, DeviceMedia, MediaFile
# media 落盘目录:默认 <项目根>/data/media(运行时资源,不入库)
DATA_DIR = settings.data_dir / "media"
COVERS_DIR = DATA_DIR / "covers"
MAX_MUSIC_BYTES = 32 * 1024 * 1024 # 32MB:一首 320kbps 无损时长的 MP3 也够
MAX_IMAGE_BYTES = 15 * 1024 * 1024 # 15MB:原图可以大,处理后会被压小
MAX_IMAGE_EDGE = 720
MUSIC_EXT = {".mp3"}
IMAGE_EXT = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".gif"}
VALID_NAME_CHARS = set(
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
" ._-()[]{}&#'@!+,;=~"
)
# FAT32 只禁这几个字符 + 控制符;中文、日文、emoji 都能存(SD_MMC 走 UTF-8 长文件名)。
# 之前用白名单只留 ASCII,结果「演唱会.mp3」被洗成「____.mp3」——设备上认不出来,
# 网页上也全是一排下划线。改成黑名单。
FAT32_FORBIDDEN = set('/\\:*?"<>|')
class MediaError(ValueError):
"""上传/处理失败,API 层直接转 400。"""
def kind_of(filename: str) -> str:
ext = Path(filename).suffix.lower()
if ext in MUSIC_EXT:
return "music"
if ext in IMAGE_EXT:
return "image"
raise MediaError(f"不支持的类型 {ext or '(无扩展名)'},仅支持 MP3 音乐和图片")
def sanitize_name(filename: str) -> str:
"""TF 卡是 FAT32:只挡 / \\ : * ? " < > | 和控制符,其余(中文等)原样保留。"""
name = Path(filename.replace("\\", "/")).name.strip()
if not name:
raise MediaError("文件名不能为空")
name = "".join("_" if (c in FAT32_FORBIDDEN or ord(c) < 32) else c for c in name)
name = name.strip(" .") # FAT32 不接受文件名以点或空格结尾
if not name:
raise MediaError("文件名不合法")
if len(name.encode("utf-8")) > 200: # FAT32 长文件名上限 255 字节,留余量
stem, ext = Path(name).stem, Path(name).suffix
name = stem[:40] + "-" + uuid.uuid4().hex[:6] + ext
return name
def process_image(data: bytes) -> tuple[bytes, int, int]:
"""转 JPEG + 限边 + 烧方向。返回 (jpeg 数据, 宽, 高)。"""
try:
from PIL import Image, ImageOps
except ImportError as e: # pragma: no cover
raise MediaError("服务端缺少 Pillow,无法处理图片(pip install Pillow)") from e
try:
img = Image.open(io.BytesIO(data))
img = ImageOps.exif_transpose(img)
if img.mode != "RGB":
img = img.convert("RGB")
img.thumbnail((MAX_IMAGE_EDGE, MAX_IMAGE_EDGE), Image.LANCZOS)
except Exception as e:
raise MediaError(f"图片无法解码:{e}") from e
out = io.BytesIO()
img.save(out, "JPEG", quality=85, optimize=True)
if out.tell() > 1024 * 1024:
out = io.BytesIO()
img.save(out, "JPEG", quality=70, optimize=True)
w, h = img.size
return out.getvalue(), w, h
def crc32_of(data: bytes) -> int:
return zlib.crc32(data) & 0xFFFFFFFF
def extract_cover(mp3: bytes, media_id: uuid.UUID) -> str:
"""抽 MP3 内嵌封面(ID3v2 APIC),压到 480px JPEG。没有封面返回 ""。
封面只是网页缩略图,压小即可;失败的任何情况(无 ID3、无 APIC、
图像解不开)都静默降级为无封面,绝不能因为封面坏而拒绝歌曲。
"""
try:
from mutagen.id3 import ID3
except ImportError: # pragma: no cover
return ""
try:
id3 = ID3(io.BytesIO(mp3), translate=False)
except Exception:
return ""
apics = id3.getall("APIC") if id3 else []
if not apics:
return ""
data = apics[0].data # 有 front 就用 front,否则拿第一个
for a in apics:
if getattr(a, "picture_type", 0) == 3: # 3 = front cover
data = a.data
break
try:
from PIL import Image
img = Image.open(io.BytesIO(data))
img = ImageOps_exif(img)
if img.mode != "RGB":
img = img.convert("RGB")
img.thumbnail((480, 480), Image.LANCZOS)
except Exception:
return ""
out = io.BytesIO()
img.save(out, "JPEG", quality=82, optimize=True)
COVERS_DIR.mkdir(parents=True, exist_ok=True)
fname = f"{media_id.hex[:12]}-cover.jpg"
(COVERS_DIR / fname).write_bytes(out.getvalue())
return fname
def ImageOps_exif(img):
"""exif_transpose 的窄封装:Pillow 老版本没有这个函数时直接原样返回。"""
try:
from PIL import ImageOps
return ImageOps.exif_transpose(img)
except Exception:
return img
def remove_cover(mf: MediaFile) -> None:
if mf.cover_file:
try:
(COVERS_DIR / mf.cover_file).unlink(missing_ok=True)
except OSError:
pass
def save_bytes(kind: str, name: str, data: bytes) -> tuple[str, int, int]:
"""落盘并返回 (filename, size, crc32)。"""
DATA_DIR.mkdir(parents=True, exist_ok=True)
filename = f"{uuid.uuid4().hex[:12]}-{kind}{Path(name).suffix.lower()}"
(DATA_DIR / filename).write_bytes(data)
return filename, len(data), crc32_of(data)
def remove_file(mf: MediaFile) -> None:
try:
(DATA_DIR / mf.filename).unlink(missing_ok=True)
except OSError:
pass
def path_of(mf: MediaFile) -> Path:
return DATA_DIR / mf.filename
def max_size_for(kind: str) -> int:
return MAX_MUSIC_BYTES if kind == "music" else MAX_IMAGE_BYTES
async def manifest_for_device(db: AsyncSession, device: Device) -> list[MediaFile]:
"""设备该同步哪些文件:绑定用户媒体库全量(设备端自己 diff,服务端不算差集)。"""
if not device.bound_user_id:
return []
stmt = select(MediaFile).where(MediaFile.owner_user_id == device.bound_user_id).order_by(MediaFile.name)
return list((await db.execute(stmt)).scalars())
def manifest_rev(files: list[MediaFile]) -> str:
"""清单指纹:内容、名字、数量任一变化都会变。
设备端只做字符串比较(快速路径),网页端也拿它判断「有没有删除/改名
这类不体现在待下载数量里的变更」。设备同步完把 rev 回报上来。
"""
h = 0
for f in sorted(files, key=lambda x: str(x.id)):
h = zlib.crc32(f"{f.id}:{f.name}:{f.size}:{f.crc32}".encode(), h)
return f"{h & 0xFFFFFFFF:08x}-{len(files):04x}"
async def pending_for_device(
db: AsyncSession, device: Device
) -> tuple[list[MediaFile], list[MediaFile]]:
"""返回 (待同步文件, 全量清单)。
待同步 = 清单里有、设备还没回报 synced 的;删除/改名不体现在这里,
但会让 rev 变化,网页端据此提示「有变更待同步」。
"""
files = await manifest_for_device(db, device)
if not files:
return [], files
synced = set(
(
await db.execute(
select(DeviceMedia.media_id).where(
DeviceMedia.device_id == device.id, DeviceMedia.state == "synced"
)
)
).scalars()
)
return [f for f in files if f.id not in synced], files
async def apply_report(
db: AsyncSession,
device: Device,
synced: list[uuid.UUID],
deleted: list[uuid.UUID],
seq: int = 0,
rev: str = "",
) -> None:
"""设备回报同步结果:upsert synced、删除已消失的记录。
只认属于该设备绑定用户的 media_id,防串库。``seq`` / ``rev`` 用来推进
同步游标——设备只在用户点了「同步」之后才会走这一步。
"""
if device.bound_user_id is None:
raise HTTPException(409, "device not bound")
owner_ids = set(
(await db.execute(select(MediaFile.id).where(MediaFile.owner_user_id == device.bound_user_id))).scalars()
)
for mid in synced:
if mid not in owner_ids:
continue
row = await db.get(DeviceMedia, (device.id, mid))
if row is None:
db.add(DeviceMedia(device_id=device.id, media_id=mid, state="synced"))
else:
row.state = "synced"
for mid in deleted:
row = await db.get(DeviceMedia, (device.id, mid))
if row is not None:
await db.delete(row)
if seq > 0:
device.media_sync_ack = seq
if rev:
device.media_synced_rev = rev
await db.commit()
async def sync_states(db: AsyncSession, user_id: uuid.UUID) -> dict[uuid.UUID, int]:
"""用户各媒体文件「已在多少台设备上」。网页列表的同步徽标数据源。"""
stmt = (
select(DeviceMedia.media_id)
.join(Device, Device.id == DeviceMedia.device_id)
.where(Device.bound_user_id == user_id, DeviceMedia.state == "synced")
)
out: dict[uuid.UUID, int] = {}
for mid in (await db.execute(stmt)).scalars():
out[mid] = out.get(mid, 0) + 1
return out