README-ko.md

유튜브 뮤직 (YouTube Music)

유튜브 뮤직의 Electron 래퍼; 기능:

• 원래의 인터페이스를 유지하는 것을 목표로 하는 네이티브 디자인 및 느낌
• 맞춤 플러그인을 위한 프레임워크: 스타일, 콘텐츠, 기능 등 필요에 따라 유튜브 뮤직을 변경하고, 클릭 한 번으로 플러그인을 활성화/비활성화할 수 있습니다.

Content

• 기능
• 사용 가능한 플러그인
• 번역
• 다운로드
  • Arch Linux
  • MacOS
  • Windows
    • (Windows에서) 네트워크에 연결하지 않고 설치하는 방법은 무엇인가요?
• 테마
• 개발
• 나만의 플러그인 만들기
  • 플러그인 만들기
  • 일반적인 사용 예
• 빌드
• 프로덕션 빌드 미리보기
• 테스트
• 라이선스
• 자주 묻는 질문

기능:

• 일시 정지 시 자동 확인 (항상 활성화 됨): 일정 시간이 지나면 음악을 일시 정지하는 "계속 시청하시겠습니까?" 팝업을 비활성화합니다.

• 이외에 더 많은 기능 ...

사용 가능한 플러그인:

• 애드블록: 모든 광고와 트래커를 즉시 차단합니다

• 앨범 컬러 기반 테마: 앨범 색상 팔레트를 기반으로 동적 테마 및 시각 효과를 적용합니다

• 앰비언트 모드: 영상의 간접 조명을 화면 배경에 투사합니다.

• 오디오 컴프레서: 오디오에 컴프레서를 적용합니다 (신호에서 가장 시끄러운 부분의 음량을 낮추고 가장 조용한 부분의 음량을 높임)

• 네비게이션 바 흐림 효과: 내비게이션 바를 투명하고 흐릿하게 만듭니다

• 나이 제한 우회: 유튜브의 나이 제한을 우회합니다

• 자막 선택기: 자막을 활성화합니다

• 컴팩트 사이드바: 사이드바를 항상 컴팩트 모드로 설정합니다

• 크로스페이드: 노래 사이에 크로스페이드 효과를 적용합니다

• 자동 재생 해제: 노래를 '일시 정지' 모드로 시작하게 합니다

• 디스코드 활동 상태: 활동 상태 (Rich Presence)를 사용하여 친구들에게 내가 듣는 음악을 보여주세요

• 다운로더: UI에서 직접 MP3/소스 오디오를 다운로드하세요

• 지수 볼륨: 음량 슬라이더를 지수적으로 만들어 더 낮은 음량을 쉽게 선택할 수 있도록 합니다.

• 인앱 메뉴: 메뉴 표시줄을 더 멋지게, 그리고 다크 또는 앨범의 색상으로 만듭니다

  (이 플러그인 및 메뉴 숨기기 옵션을 활성화한 후 메뉴에 액세스하는 데 문제가 있는 경우 이 글을 참조하세요)

• Last.fm: Last.fm에 대한 스크러블 지원을 추가합니다

• Lumia Stream: Lumia Stream 지원을 추가합니다

• Genius 가사: 더 많은 곡에 대해 가사 지원을 추가합니다

• 네비게이션: 브라우저에서처럼, UI에 직접 통합된 앞으로/뒤로 탐색하는 화살표를 추가합니다

• Google 로그인 제거: UI에서 Google 로그인 버튼 및 링크 제거하기

• 알림: 노래 재생이 시작되면 알림을 표시 (Windows에서는 대화형 알림 사용 가능)

• PiP: 앱을 PiP 모드로 전환할 수 있게 허용합니다

• 재생 속도: 빨리 듣거나, 천천히 들어보세요! 노래 속도를 제어하는 슬라이더를 추가합니다

• 정확한 음량: 사용자 지정 HUD와 사용자 지정 음량 단계 및 마우스 휠/단축키를 사용하여 음량을 정확하게 제어하세요

• 영상 품질 체인저: 영상 오버레이의 버튼으로 영상 품질을 변경할 수 있게 합니다

• 단축키 (& MPRIS): 재생을 위한 전역 단축키 설정 허용 (재생/일시 정지/다음/이전) + 미디어 키를 재정의하여 미디어 osd 비활성화 + Ctrl/CMD + F 검색 활성화 + 미디어 키에 대한 리눅스 MPRIS 지원 활성화 + 고급 사용자를 위한 사용자 지정 단축키 지원

• 무음 건너뛰기 - 노래의 무음 부분을 자동으로 건너뜁니다

• SponsorBlock: 인트로/아웃트로와 같은 음악이 아닌 부분이나, 노래가 재생되지 않는 뮤직 비디오의 일부를 자동으로 건너뜁니다

• 작업표시줄 미디어 컨트롤: Windows 작업표시줄에서 재생을 제어하세요

• TouchBar: macOS 사용자를 위한 TouchBar 위젯을 추가합니다

• Tuna-OBS: OBS의 플러그인, Tuna와 통합을 활성화합니다

• 영상 전환: 영상/노래 모드를 전환하는 버튼을 추가합니다. 선택적으로 전체 영상 탭을 제거할 수도 있습니다

• 비주얼라이저: 플레이어에 시각화 도구 추가

번역

Hosted Weblate에서 번역을 도울 수 있습니다.

다운로드

최신 릴리즈를 확인하여 최신 버전을 빠르게 찾을 수 있습니다.

Arch Linux

AUR에서 youtube-music-bin 패키지를 설치합니다. AUR 설치 지침은 이 위키 페이지를 참조하세요.

MacOS

Homebrew를 사용하여 앱을 설치할 수 있습니다:

brew install --cask https://raw.githubusercontent.com/th-ch/youtube-music/master/youtube-music.rb

(앱을 수동으로 설치하고) 앱을 실행할 때 손상되었기 때문에 열 수 없습니다.라는 오류가 발생하면 터미널에서 다음을 실행하세요:

xattr -cr /Applications/YouTube\ Music.app

Windows

Scoop 패키지 매니저를 사용하여 extras 버킷에서 youtube-music 패키지를 설치할 수 있습니다.

scoop bucket add extras
scoop install extras/youtube-music

또는 Windows 11의 공식 CLI 패키지 관리자인 Winget을 사용하여 th-ch.YouTubeMusic 패키지를 설치할 수 있습니다.

참고: "알 수 없는 게시자"의 파일이기 때문에 Microsoft Defender의 SmartScreen에서 설치를 차단할 수 있습니다. 이는 GitHub에서 동일 파일을 수동으로 다운로드한 후 실행 파일(.exe)을 실행하려고 할 때도 마찬가지로 발생합니다.

winget install th-ch.YouTubeMusic

(Windows에서) 네트워크에 연결하지 않고 설치하는 방법은 무엇인가요?

• 릴리즈 페이지에서 _본인 기기 아키텍처_에 맞는 *.nsis.7z 파일을 다운로드하세요.
  • x64는 64비트 Windows 용입니다.
  • ia32는 32비트 Windows 용입니다.
  • arm64는 ARM64 Windows 용입니다.
• 릴리즈 페이지에서 설치기를 다운로드하세요. (*-Setup.exe)
• 두 파일을 동일한 위치에 놓아주세요.
• 설치기를 실행하세요.

테마

CSS 파일을 로드하여 애플리케이션의 모양을 변경할 수 있습니다(설정 > 시각적 변경 > 테마).

일부 사전 정의 테마는 https://github.com/kerichdev/themes-for-ytmdesktop-player 에서 사용할 수 있습니다.

개발

git clone https://github.com/th-ch/youtube-music
cd youtube-music
pnpm install --frozen-lockfile
pnpm dev

나만의 플러그인 만들기

플러그인을 사용하면 할 수 있는 것들:

• 앱 조작 - Electron에서 BrowserWindow가 플러그인 핸들러로 전달
• HTML/CSS를 조작하여 프론트엔드를 변경

플러그인 만들기

plugins/나만의-플러그인-이름에 폴더를 만듭니다:

• index.ts: 플러그인의 메인 파일입니다.

import style from './style.css?inline'; // 스타일을 인라인으로 가져옵니다

import { createPlugin } from '@/utils';

export default createPlugin({
  name: 'Plugin Label',
  restartNeeded: true, // 값이 true면, YTM은 재시작 다이얼로그를 표시합니다
  config: {
    enabled: false,
  }, // 나의 커스텀 config
  stylesheets: [style], // 나의 스타일
  menu: async ({ getConfig, setConfig }) => {
    // 모든 *Config 메서드는 Promise<T>로 래핑됩니다
    const config = await getConfig();
    return [
      {
        label: 'menu',
        submenu: [1, 2, 3].map((value) => ({
          label: `value ${value}`,
          type: 'radio',
          checked: config.value === value,
          click() {
            setConfig({ value });
          },
        })),
      },
    ];
  },
  backend: {
    start({ window, ipc }) {
      window.maximize();

      // 이를 사용하여 렌더러 플러그인과 통신할 수 있습니다
      ipc.handle('some-event', () => {
        return 'hello';
      });
    },
    // config가 변경되면 실행됩니다
    onConfigChange(newConfig) { /* ... */ },
    // 플러그인이 비활성화되면 실행됩니다
    stop(context) { /* ... */ },
  },
  renderer: {
    async start(context) {
      console.log(await context.ipc.invoke('some-event'));
    },
    // 렌더러에서만 사용 가능한 훅입니다
    onPlayerApiReady(api: YoutubePlayer, context: RendererContext<T>) {
      // 플러그인의 config를 간단하게 설정할 수 있습니다
      context.setConfig({ myConfig: api.getVolume() });
    },
    onConfigChange(newConfig) { /* ... */ },
    stop(_context) { /* ... */ },
  },
  preload: {
    async start({ getConfig }) {
      const config = await getConfig();
    },
    onConfigChange(newConfig) {},
    stop(_context) {},
  },
});

일반적인 사용 예

• 사용자 정의 CSS 삽입: 같은 폴더에 style.css 파일을 생성합니다:

// index.ts
import style from './style.css?inline'; // 스타일을 인라인으로 가져옵니다

import { createPlugin } from '@/utils';

export default createPlugin({
  name: 'Plugin Label',
  restartNeeded: true, // 값이 true면, YTM은 재시작 다이얼로그를 표시합니다
  config: {
    enabled: false,
  }, // 나의 커스텀 config
  stylesheets: [style], // 나의 커스텀 스타일
  renderer() {} // 렌더러 훅 정의
});

• HTML을 변경하려는 경우:

import { createPlugin } from '@/utils';

export default createPlugin({
  name: 'Plugin Label',
  restartNeeded: true, // 값이 true면, YTM은 재시작 다이얼로그를 표시합니다
  config: {
    enabled: false,
  }, // 나의 커스텀 config
  renderer() {
    // 로그인 버튼을 제거합니다
    document.querySelector(".sign-in-link.ytmusic-nav-bar").remove();
  } // 렌더러 훅 정의
});

• 프론트엔드와 백엔드 간의 통신: Electron의 ipcMain 모듈을 사용하여 수행할 수 있습니다. SponsorBlock 플러그인의 index.ts 파일과 예제를 참조하세요.

빌드

1. 레포지토리를 복제 (clone) 합니다
2. 이 가이드에 따라 pnpm을 설치합니다.
3. pnpm install --frozen-lockfile을 실행하여 종속성을 설치합니다.
4. pnpm build:OS을 실행합니다.

• pnpm dist:win - Windows
• pnpm dist:linux - Linux
• pnpm dist:mac - MacOS

electron-builder를 사용하여 macOS, Linux 및 Windows용 앱을 빌드합니다.

프로덕션 빌드 미리보기

pnpm start

테스트

pnpm test

Playwright를 사용하여 앱을 테스트합니다.

라이선스

MIT © th-ch

자주 묻는 질문

앱 메뉴가 표시되지 않는 이유는 무엇인가요?

메뉴 숨기기 옵션이 켜져 있는 경우 - alt 키(또는 인앱 메뉴 플러그인을 사용하는 경우 ` [백틱] 키)로 메뉴를 표시할 수 있습니다.