📥 Instalação¶

Este guia orienta a instalação do Gingo em diferentes plataformas e ambientes.

Requisitos do Sistema¶

graph TD
    A[Requisitos] --> B[Python 3.10+]
    A --> C[pip]
    A --> D[Terminal/Shell]

    B --> B1[Incluído na distribuição<br/>Python oficial]
    C --> C1[Gerenciador de pacotes<br/>Python padrão]
    D --> D1[Interface de linha<br/>de comando]

    style A fill:#FFD700,stroke:#FF8C00,stroke-width:4px,color:#000
    style B fill:#87CEEB,stroke:#4169E1,stroke-width:3px,color:#000
    style C fill:#98FB98,stroke:#32CD32,stroke-width:3px,color:#000
    style D fill:#FFB6C1,stroke:#FF1493,stroke-width:3px,color:#000
    style B1 fill:#E0FFE0,stroke:#228B22,stroke-width:2px,color:#000
    style C1 fill:#E0FFE0,stroke:#228B22,stroke-width:2px,color:#000
    style D1 fill:#E0FFE0,stroke:#228B22,stroke-width:2px,color:#000

Sobre o terminal

O terminal é uma interface textual para comunicação com o sistema operacional:

Windows: Prompt de Comando ou PowerShell
macOS: Terminal
Linux: Terminal (shell padrão)

Passo 1: Verificar Instalação do Python¶

Windows¶

Pressione Win + R
Digite cmd e pressione Enter
Execute:

python --version

macOS / Linux¶

Abra o Terminal
Execute:

python3 --version

Interpretação dos Resultados¶

flowchart TD
    A[Comando executado] --> B{Saída?}

    B -->|Python 3.10 ou superior| C[Instalação válida]
    B -->|Python 3.9 ou inferior| D[Atualização necessária]
    B -->|Comando não reconhecido| E[Instalação necessária]

    C --> F[Prosseguir para Passo 2]
    D --> G[Baixar em<br/>python.org]
    E --> G

    style A fill:#87CEEB,stroke:#4169E1,stroke-width:3px,color:#000
    style B fill:#FFD700,stroke:#FF8C00,stroke-width:3px,color:#000
    style C fill:#98FB98,stroke:#32CD32,stroke-width:3px,color:#000
    style D fill:#FFE5B4,stroke:#FF8C00,stroke-width:3px,color:#000
    style E fill:#FFB6C1,stroke:#FF1493,stroke-width:3px,color:#000
    style F fill:#E0FFE0,stroke:#228B22,stroke-width:3px,color:#000
    style G fill:#87CEEB,stroke:#4169E1,stroke-width:2px,color:#000

Saída esperada

Python 3.12.0

Qualquer versão ≥ 3.10 é compatível.

Instalação do Python

Se o Python não estiver instalado:

Acesse python.org/downloads
Baixe o instalador apropriado
Execute a instalação
IMPORTANTE (Windows): Marque a opção "Add Python to PATH"

Passo 2: Instalar o Gingo¶

sequenceDiagram
    participant U as Usuário
    participant T as Terminal
    participant P as pip
    participant G as Gingo

    U->>T: Abre terminal
    U->>T: pip install gingo
    T->>P: Solicita instalação
    P->>G: Baixa e instala
    G->>P: Instalação concluída
    P->>T: Confirmação
    T->>U: Sucesso

Comando de Instalação¶

WindowsmacOS / Linux

pip install gingo

pip3 install gingo

Saída Esperada¶

Durante a instalação, você verá:

Collecting gingo
  Downloading gingo-1.0.1-cp312-cp312-win_amd64.whl (245 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 245.0/245.0 kB 5.2 MB/s
Installing collected packages: gingo
Successfully installed gingo-1.0.1

Instalação bem-sucedida

A mensagem Successfully installed gingo-X.X.X confirma a instalação.

Erros de instalação

Consulte a seção "Solução de Problemas" abaixo.

Passo 3: Verificação da Instalação¶

Verificação via CLI¶

Execute:

gingo --version

Saída esperada:

gingo 1.0.1

flowchart LR
    A[gingo --version] --> B{Resultado?}

    B -->|Versão exibida| C[Instalação válida]
    B -->|Comando não encontrado| D[Erro na instalação]

    C --> E[Prosseguir para teste Python]
    D --> F[Consultar troubleshooting]

    style A fill:#87CEEB,stroke:#4169E1,stroke-width:3px,color:#000
    style B fill:#FFD700,stroke:#FF8C00,stroke-width:3px,color:#000
    style C fill:#98FB98,stroke:#32CD32,stroke-width:3px,color:#000
    style D fill:#FFB6C1,stroke:#FF1493,stroke-width:3px,color:#000
    style E fill:#E0FFE0,stroke:#228B22,stroke-width:2px,color:#000
    style F fill:#FFE5B4,stroke:#FF8C00,stroke-width:2px,color:#000

Verificação via Python¶

Entre no interpretador interativo:

python

Ou no macOS/Linux:

python3

Execute:

from gingo import Note, Chord, Scale
print(Note("C"))
print(Chord("C"))
print(Scale("C", "major"))

Saída esperada:

C
C
C Major

Para sair do interpretador:

exit()

graph TD
    A[Abrir interpretador] --> B[Importar gingo]
    B --> C{Sucesso?}

    C -->|Sim| D[Instalação verificada]
    C -->|ModuleNotFoundError| E[Erro de importação]

    D --> F[Pronto para uso]
    E --> G[Consultar troubleshooting]

    style A fill:#87CEEB,stroke:#4169E1,stroke-width:3px,color:#000
    style B fill:#DDA0DD,stroke:#9370DB,stroke-width:3px,color:#000
    style C fill:#FFD700,stroke:#FF8C00,stroke-width:3px,color:#000
    style D fill:#98FB98,stroke:#32CD32,stroke-width:3px,color:#000
    style E fill:#FFB6C1,stroke:#FF1493,stroke-width:3px,color:#000
    style F fill:#E0FFE0,stroke:#228B22,stroke-width:4px,color:#000
    style G fill:#FFE5B4,stroke:#FF8C00,stroke-width:2px,color:#000

Instalação confirmada

Se ambos os testes foram bem-sucedidos, o Gingo está operacional.

Próximo passo: Conceitos Básicos

🔧 Solução de Problemas¶

Problema 1: "pip não é reconhecido"¶

graph TD
    A[Erro: pip não reconhecido] --> B[Causa: Python não no PATH]
    B --> C[Solução 1:<br/>Reinstalar Python]
    B --> D[Solução 2:<br/>Usar python -m pip]

    C --> C1[Marcar 'Add to PATH'<br/>na instalação]
    D --> D2[python -m pip install gingo]

    style A fill:#FFB6C1,stroke:#FF1493,stroke-width:3px,color:#000
    style B fill:#FFE5B4,stroke:#FF8C00,stroke-width:3px,color:#000
    style C fill:#87CEEB,stroke:#4169E1,stroke-width:2px,color:#000
    style D fill:#98FB98,stroke:#32CD32,stroke-width:2px,color:#000
    style C1 fill:#E0FFE0,stroke:#228B22,stroke-width:2px,color:#000
    style D2 fill:#E0FFE0,stroke:#228B22,stroke-width:2px,color:#000

Solução rápida:

python -m pip install gingo

Problema 2: "Permission denied" ou "Access denied"¶

Erro relacionado a permissões insuficientes.

Solução:

WindowsmacOS / Linux

Execute o terminal como Administrador:

Localize "cmd" ou "PowerShell" no menu Iniciar
Clique com botão direito
Selecione "Executar como administrador"
Execute novamente o comando de instalação

Use sudo para elevar privilégios:

sudo pip3 install gingo

Digite sua senha quando solicitado (a entrada não é exibida visualmente).

Problema 3: "No module named 'gingo'"¶

flowchart TD
    A[ModuleNotFoundError] --> B{Versão de Python?}

    B -->|python| C[Instalar com<br/>python -m pip]
    B -->|python3| D[Instalar com<br/>python3 -m pip]

    C --> E[Executar com<br/>python]
    D --> F[Executar com<br/>python3]

    E --> G[Problema resolvido]
    F --> G

    style A fill:#FFB6C1,stroke:#FF1493,stroke-width:3px,color:#000
    style B fill:#FFD700,stroke:#FF8C00,stroke-width:3px,color:#000
    style C fill:#87CEEB,stroke:#4169E1,stroke-width:2px,color:#000
    style D fill:#87CEEB,stroke:#4169E1,stroke-width:2px,color:#000
    style E fill:#DDA0DD,stroke:#9370DB,stroke-width:2px,color:#000
    style F fill:#DDA0DD,stroke:#9370DB,stroke-width:2px,color:#000
    style G fill:#98FB98,stroke:#32CD32,stroke-width:3px,color:#000

Solução: Consistência entre instalação e execução:

# Instalar
python -m pip install gingo

# Executar
python
>>> from gingo import Note

Problema 4: Versão desatualizada do pip¶

Se aparecer aviso:

WARNING: You are using pip version 20.0.0; however, version 24.0 is available.

Solução: Atualizar o pip:

python -m pip install --upgrade pip

Após a atualização, instale o Gingo normalmente.

🌟 Instalação Avançada¶

Para desenvolvedores e casos de uso específicos.

Instalação com Audio (playback)¶

pip install gingo[audio]

Instala simpleaudio para playback direto pelo alto-falante. A sintese de audio e exportacao WAV funcionam sem dependencias extras — gingo[audio] e necessario apenas para o .play() tocar som pelo sistema.

Sem simpleaudio, o Gingo tenta players do sistema (aplay/paplay/ffplay no Linux, afplay no macOS).

Instalação com Dependências de Teste¶

pip install gingo[test]

Instalação Completa¶

pip install gingo[audio,test]

graph TD
    A[gingo] --> B[Instalação<br/>Padrão]
    A --> C[gingo dev]
    A --> D[gingo test]
    A --> E[gingo dev,test]

    B --> B1[Uso normal]
    C --> C1[Desenvolvimento]
    D --> D1[Testes]
    E --> E1[Completo]

    style A fill:#FFD700,stroke:#FF8C00,stroke-width:4px,color:#000
    style B fill:#98FB98,stroke:#32CD32,stroke-width:3px,color:#000
    style C fill:#87CEEB,stroke:#4169E1,stroke-width:2px,color:#000
    style D fill:#DDA0DD,stroke:#9370DB,stroke-width:2px,color:#000
    style E fill:#FFB6C1,stroke:#FF1493,stroke-width:2px,color:#000

🆘 Suporte Adicional¶

Se os problemas persistirem:

mindmap
  root((Suporte))
    GitHub Issues
      Descrever problema
      Incluir logs de erro
      Informar versões
    Documentação
      FAQ
      Exemplos
      API Reference
    Comunidade
      Fóruns Python
      Stack Overflow
      Reddit r/learnpython

Informações para suporte

Ao reportar problemas, inclua:

Sistema operacional e versão
Versão do Python (python --version)
Mensagem de erro completa
Comandos executados

🎉 Instalação Concluída¶

journey
    title Processo de Instalação
    section Preparação
      Verificar Python: 5: Usuário
      Abrir Terminal: 5: Usuário
    section Instalação
      pip install gingo: 5: pip
      Download: 3: pip
    section Verificação
      Testar CLI: 5: Usuário
      Testar importação: 5: Usuário
    section Resultado
      Instalação confirmada: 5: Sucesso

Próximos Passos¶

Agora que o Gingo está instalado:

Conceitos Básicos - Fundamentos de teoria musical
Primeiros Passos - Exemplos práticos de código
Começando - Casos de uso avançados

graph LR
    A[Instalação<br/>Completa] --> B[Conceitos<br/>Básicos]
    B --> C[Primeiros<br/>Passos]
    C --> D[Começando]
    D --> E[Domínio]

    style A fill:#98FB98,stroke:#32CD32,stroke-width:4px,color:#000
    style B fill:#87CEEB,stroke:#4169E1,stroke-width:3px,color:#000
    style C fill:#FFB6C1,stroke:#FF1493,stroke-width:3px,color:#000
    style D fill:#DDA0DD,stroke:#9370DB,stroke-width:3px,color:#000
    style E fill:#FFD700,stroke:#FF8C00,stroke-width:4px,color:#000

Próxima etapa: Conceitos Básicos

Continue para Conceitos Básicos para compreender os fundamentos teóricos.

💡 Dica: Salve esta página para referência futura em caso de reinstalação ou troubleshooting.