# Qingtian Technical Detail Record — 2026-08-30

# RemoteOffice / Qingtian Multimedia
## YouTube Online Search Integration — Technical Record

---

## 1. Objective

Add a YouTube online search capability to the existing **Qingtian Multimedia** system.

Required flow:

1. User enters a search query.
2. RemoteOffice FastAPI backend receives the query.
3. `yt-dlp` searches YouTube.
4. Structured search results are returned.
5. Results are displayed inside Qingtian Multimedia.

---

## 2. Project Context

Project directory:

```text
/home/foo/RemoteOffice
```

Main application entry:

```text
app/main.py
```

Multimedia front-end:

```text
templates/qingtian_multimedia.html
```

Docker service:

```text
remoteoffice
```

Stack involved:

- FastAPI
- Uvicorn
- Docker / docker-compose
- Python
- yt-dlp
- Existing Qingtian Multimedia interface

---

## 3. Host-side yt-dlp Verification

The host executable was verified at:

```text
/home/foo/.local/bin/yt-dlp
```

Verified version:

```text
2026.08.19
```

Successful host-side search example:

```text
/home/foo/.local/bin/yt-dlp "ytsearch3:You Raise Me Up"
```

Structured metadata test:

```text
/home/foo/.local/bin/yt-dlp \
  "ytsearch3:You Raise Me Up" \
  --skip-download \
  --print "%(id)s | %(title)s | %(channel)s | %(webpage_url)s"
```

This successfully returned results including Westlife and Josh Groban versions of **You Raise Me Up**.

Warnings about Python 3.10 deprecation and the lack of a supported JavaScript runtime appeared during host testing, but the search itself succeeded.

---

## 4. Backend Router

New backend file:

```text
app/youtube.py
```

Implemented endpoint:

```text
GET /qingtian/youtube/search
```

Query parameter:

```text
q
```

Search command logic uses:

```text
ytsearch10:<search query>
```

Returned fields:

```text
id
title
channel
webpage_url
thumbnail
```

Successful JSON shape:

```json
{
  "count": 10,
  "videos": [
    {
      "id": "...",
      "title": "...",
      "channel": "...",
      "url": "...",
      "thumbnail": "..."
    }
  ]
}
```

---

## 5. Router Registration

`app/main.py` was updated to import:

```python
from app.youtube import router as youtube_router
```

And register:

```python
app.include_router(youtube_router)
```

This made the endpoint available through the existing FastAPI application.

---

## 6. Docker Environment Issue

The first backend version pointed to the host executable:

```text
/home/foo/.local/bin/yt-dlp
```

The RemoteOffice application, however, runs inside Docker.

Therefore the Docker container could not access the host user's executable path, producing:

```json
{"detail":"yt-dlp not found"}
```

Important conclusion:

> Software installed in the host user environment is not automatically available inside a Docker container.

---

## 7. Dockerfile Fix

Original dependency installation:

```dockerfile
RUN pip install --no-cache-dir -r requirements.txt
```

Updated installation:

```dockerfile
RUN pip install --no-cache-dir -r requirements.txt yt-dlp
```

The image already installs:

```text
ffmpeg
```

After rebuilding, `yt-dlp` became available inside the Python 3.12 container environment.

---

## 8. Docker Compose Recreation Issue

During recreation, legacy `docker-compose` produced:

```text
KeyError: 'ContainerConfig'
```

The stopped old container was removed manually.

The service was then recreated successfully and later showed:

```text
remoteoffice   Up
```

---

## 9. Successful API Verification

Final test:

```text
curl -s "http://localhost:8000/qingtian/youtube/search?q=You%20Raise%20Me%20Up"
```

Successful result:

- `count: 10`
- video IDs
- titles
- channel names
- YouTube URLs
- thumbnail URLs

This confirmed the backend integration end-to-end.

---

## 10. Front-End Integration

File:

```text
templates/qingtian_multimedia.html
```

Function:

```text
searchYouTube()
```

Front-end flow:

1. Read input from `youtube-search`.
2. Request:
   ```text
   /qingtian/youtube/search?q=<encoded query>
   ```
3. Parse JSON.
4. Render cards containing:
   - thumbnail
   - title
   - channel
   - Play YouTube button

Current button behavior opens the YouTube URL externally.

---

## 11. UI Verification

The final Qingtian Multimedia page contains:

### Qingtian Music
Existing music functions.

### Qingtian Video
Existing NAS video functions.

### Voice Search
Existing voice search/command area.

### YouTube
New online YouTube search section.

The YouTube section successfully displayed the search results in a vertical card layout with internal scrolling.

Visible examples included:

1. Westlife — You Raise Me Up (Official Video)
2. Josh Groban — You Raise Me Up (Official Music Video) [HD Remaster]
3. You Raise Me Up — Westlife (Lyrics)
4. Martin Hurkens — You Raise me Up

---

## 12. Final Architecture

```text
Browser
   ↓
Qingtian Multimedia
   ↓
YouTube Search Input
   ↓
FastAPI
/qingtian/youtube/search
   ↓
app/youtube.py
   ↓
yt-dlp inside Docker container
   ↓
YouTube Search
   ↓
JSON Results
   ↓
Thumbnail + Title + Channel + Play Button
```

---

## 13. Files Involved

```text
app/youtube.py
app/main.py
templates/qingtian_multimedia.html
Dockerfile
requirements.txt
```

Backup files created during work included:

```text
requirements.txt.before-youtube
Dockerfile.before-youtube
```

---

## 14. Current Confirmed Status

| Component | Status |
|---|---|
| Host yt-dlp | Confirmed working |
| Docker yt-dlp | Installed and working |
| FastAPI YouTube router | Working |
| `/qingtian/youtube/search` | Working |
| JSON results | Working |
| Thumbnail output | Working |
| Qingtian Multimedia display | Working |
| Result scrolling | Working |
| Open YouTube button | Implemented |
| Direct in-page YouTube playback | Not implemented / not confirmed |

---

## 15. Recommended Next Phase

**YouTube Playback Phase 2**

Possible next work:

1. Evaluate direct playback inside Qingtian Multimedia.
2. Keep external YouTube opening as a fallback.
3. Improve result card sizing for different screens.
4. Add additional loading/error feedback if needed.
5. Consider configurable result count or pagination.
6. Preserve this working Search Phase 1 checkpoint before major changes.

---

# Final Technical Conclusion

**Qingtian / RemoteOffice YouTube Online Search Phase 1 is successfully completed.**

Verified end-to-end flow:

```text
User Search
→ FastAPI
→ yt-dlp in Docker
→ YouTube Search Results
→ JSON
→ Qingtian Multimedia UI
```

The main technical issue solved was the separation between the IEI Server host environment and the Docker container environment. Installing `yt-dlp` inside the Docker image resolved the API error:

```text
yt-dlp not found
```

The current implementation is a stable working checkpoint for future YouTube playback improvements.